Server Quality Checklist

Tool Scores

• send_mmsB
  3.1/5.0
  Behavior2/5

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

  Annotations already indicate non-read-only and non-destructive behavior. The description adds no extra context such as media constraints, auth requirements, rate limits, or success/failure response behavior. It merely restates the action without augmenting the safety profile.

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

  Conciseness4/5

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

  The description is a single, concise sentence that front-loads the core action. It contains no redundant information, though it is slightly too terse to be maximally informative. It earns a 4 for efficiency and structure.

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

  Completeness2/5

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

  With no output schema and 7 parameters including constraints like Australia-only recipients and media size limits, the description is notably incomplete. It does not explain return values, send confirmation, or error behavior, leaving significant gaps for an agent to invoke the tool correctly.

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

  Parameters3/5

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

  The input schema provides 100% coverage for all 7 parameters, including detailed descriptions of formats, constraints, and content types. The description adds no additional parameter meaning, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool sends an MMS (media) message to a recipient, using a specific verb and resource. It distinguishes from sibling tools like send_sms and send_whatsapp by explicitly mentioning 'media', making the purpose unambiguous.

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

  Usage Guidelines2/5

  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 such as send_sms or send_whatsapp. There is no mention of exclusions, prerequisites, or preferred scenarios, leaving the agent to infer usage independently.

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

• add_contact_to_listA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive write. The description adds the KUDOSITY_API_SECRET requirement and clarifies that 'contact' means mobile number. However, it does not disclose idempotency, duplicate handling, or return behavior, which would be valuable 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.

  Conciseness5/5

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

  The description is two short sentences, front-loading the core purpose and then stating the auth requirement. No redundant words or repetition of schema information.

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

  Completeness3/5

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

  For a mutation tool with no output schema, the description is minimal. It covers the operation and auth but omits expected response, error cases, and duplicate behavior. Given the five parameters and sibling context, this is adequate but leaves notable 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?

  All five parameters are fully described in the schema, so the baseline is 3 per the rubric. The description's mention of 'mobile number' reinforces the 'number' parameter but adds no new semantic detail beyond the schema.

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

  Purpose5/5

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

  The description clearly states the action: adding a mobile number as a contact to a list. It uses a specific verb and resource, and distinguishes from sibling tools like remove_contact_from_list by specifying the add operation and contact type.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool (when adding a contact to a list) but does not explicitly contrast with alternatives or provide when-not-to-use guidance. It mentions an auth prerequisite, which adds context, but no exclusions or alternative tool references.

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

• delete_webhookA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no further behavioral context (e.g., permanence, cascading effects, or required permissions), which with annotations present is acceptable but not enhanced.

  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 one sentence, front-loaded, and contains no extraneous words.

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

  Completeness4/5

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

  For a simple delete tool with full schema coverage and annotations indicating destructiveness, the description adequately covers the purpose. There is no output schema, so return-value detail is not required; however, a note about irreversibility could enhance completeness.

  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 already fully describes the sole parameter 'id' with 'The webhook ID to delete.' The description repeats this without adding any additional semantic nuance, so it provides no value beyond the schema.

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

  Purpose5/5

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

  The description uses the specific verb 'delete' with the resource 'webhook' and identifies the key identifier ('by its ID'), clearly distinguishing it from sibling tools such as delete_list and create_webhook.

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

  Usage Guidelines3/5

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

  It does not provide explicit guidance on when to use this tool or mention alternatives. However, given the straightforward nature of a delete operation and the sibling list showing no other webhook deletion tool, the usage is implied. It lacks exclusions or prerequisites.

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

• get_listA
  3.8/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true and openWorldHint=true, which align with the description. Beyond that, the description discloses an authentication requirement (KUDOSITY_API_SECRET), which is not present in the annotations or schema. It does not mention potential errors or return format, but the read-only nature is clear.

  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, clear sentence that immediately states the action and the optional members behavior, with no filler or redundant information.

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

  Completeness4/5

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

  For a simple 2-parameter, 1-required-parameter tool with full schema coverage and readOnly/openWorld annotations, the description is mostly sufficient. The main gap is the lack of any return format or error behavior, but given no output schema and the simplicity of the operation, this is acceptable.

  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 already described ('Numeric list ID' and 'Include member contacts in the response'). The description only mirrors the 'members' behavior already present in the schema, adding no new semantic context.

  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 uses a specific verb ('get') and resource ('contact list'), and adds the distinct capability of optionally including members. However, it does not explicitly differentiate from the sibling tool 'get_lists', relying on singular vs. plural naming to convey the difference.

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

  Usage Guidelines3/5

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

  The description implies usage for retrieving a single list by ID, and mentions the auth prerequisite (KUDOSITY_API_SECRET). However, it does not explicitly state when to use this tool versus alternatives like get_lists, delete_list, or create_list, nor does it provide exclusion criteria.

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

• delete_listA
  3.9/5.0
  Behavior3/5

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

  The destructiveHint annotation already communicates the destructive nature, and the description adds the authentication requirement (KUDOSITY_API_SECRET) and v1 auth context. However, it does not disclose other potential behavioral traits such as irreversibility or side effects beyond what the annotation implies.

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

  Conciseness5/5

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

  The description is a single concise sentence that front-loads the action and resource, immediately followed by the auth requirement. No waste or redundancy.

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

  Completeness5/5

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

  For a simple one-parameter delete operation, the description, combined with the schema and annotations (destructiveHint, readOnlyHint), provides all necessary context: what it does, the required parameter, auth needs, and destructive nature. No output schema is needed, and no missing details are apparent.

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

  Parameters3/5

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

  The schema covers the single parameter list_id with a clear description ('Numeric list ID to delete'), and the description reiterates 'by ID'. Since schema coverage is 100%, the description adds no additional semantic meaning beyond confirming the parameter's role.

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

  Purpose5/5

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

  The description states the specific action ('Delete'), the resource ('contact list'), and the required identifier ('by ID'). It clearly distinguishes from sibling tools like 'remove_contact_from_list' and 'delete_webhook' by targeting the contact list resource specifically.

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

  Usage Guidelines3/5

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

  The description implies the tool is used when a contact list needs to be permanently removed, but it does not explicitly state when to choose this over alternatives or mention any exclusions. It does provide the usage context that KUDOSITY_API_SECRET is required, which is helpful but does not offer full guidance.

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

• send_smsA
  3.9/5.0
  Behavior3/5

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

  Annotations already disclose this as a non-read-only, non-destructive, open-world operation. The description adds minimal context by mentioning 'via Kudosity' and 'single recipient', but does not discuss charges, delivery behavior, or failure outcomes, which are useful for a side-effect operation.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that directly states the action and scope. Every word is meaningful with no unnecessary filler.

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

  Completeness3/5

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

  While request parameters are fully documented and annotations cover safety, the absence of an output schema means the description should clarify return values (e.g., message ID) or prerequisites like account balance. It does not, leaving a moderate gap for 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?

  Input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description itself adds no additional parameter meaning beyond the schema, but also does not need to since the schema is thorough.

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

  Purpose5/5

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

  The description states a specific action ('Send an SMS text message') with a clear resource target ('single recipient via Kudosity'), effectively distinguishing it from sibling tools like send_mms and send_whatsapp by specifying SMS and single-recipient scope.

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

  Usage Guidelines4/5

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

  The description clearly implies use when an SMS needs to be sent to one recipient, but does not explicitly provide exclusions or mention alternatives (e.g., 'for multimedia use send_mms'). It gives a clear context without going further.

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

• create_listA
  4/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false and destructiveHint=false, so the description correctly aligns as a write operation. It adds valuable behavioral context by noting the required KUDOSITY_API_SECRET (v1 auth), which is not present in annotations. It does not mention potential failures or side effects, but the auth requirement is a meaningful addition beyond structured data.

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

  Conciseness5/5

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

  The description is concise, two sentences, and front-loaded with the core action. It avoids redundancy with the title and schema, only adding the essential auth requirement. Every word earns its place.

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

  Completeness4/5

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

  Given the simple one-parameter create operation, the description is nearly complete. It doesn't explain the return value (since no output schema is provided), but the typical behavior of a create tool is implied. The auth requirement adds context, and the sibling tools provide an ecosystem understanding. Slightly more detail on response or error cases would make it perfect, but it's sufficient for straightforward 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 covers 100% of parameters, including the 'name' property with a description. The tool description does not add extra semantic detail about parameters, such as uniqueness constraints or formatting, beyond what the schema already states. Baseline 3 is appropriate since schema already handles parameter meaning.

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

  Purpose5/5

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

  The description 'Create a new contact list' clearly states the verb and resource, distinguishing it from sibling tools like get_list, delete_list, and add_contact_to_list. The title reinforces the purpose, leaving no ambiguity about what this tool does.

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

  Usage Guidelines3/5

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

  The description implies usage by stating the action, but it does not explicitly mention when to choose this tool over alternatives or provide exclusions. For instance, it doesn't say 'use this after creating an endpoint' or 'use get_list to retrieve existing lists'. The context is clear enough for the simple create operation, but guidance is implied rather than explicit.

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

• create_webhookA
  4/5.0
  Behavior4/5

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

  Annotations already indicate a write operation (readOnlyHint: false) and an open-world side effect (openWorldHint: true). The description adds useful behavioral context by enumerating the event types the webhook receives, making the external callback behavior clear. It does not cover auth or duplicate handling, but annotations lower the burden.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with a clear verb-object structure and a concise list of event categories. Every word adds value, with no filler or repetition.

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

  Completeness4/5

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

  Given the detailed schema, clear annotations, and sibling tool context, the description is sufficient for an agent to select and invoke the tool. It could mention the response or post-creation behavior, but the core purpose and subscription semantics are clearly conveyed, so the tool remains usable.

  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?

  All 6 parameters have descriptions in the JSON schema (100% coverage), so the description does not need to repeat parameter-level details. It adds a high-level mapping to event types but does not elaborate on rate_limit or senders beyond what the schema already states. This matches the baseline for high schema coverage.

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

  Purpose5/5

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

  The description uses the specific verb 'Register' with the resource 'webhook' and explains its purpose: to receive event callbacks such as delivery status, inbound messages, link hits, and opt-outs. This clearly distinguishes it from sibling tools like list_webhooks and delete_webhook.

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

  Usage Guidelines3/5

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

  The description implies the tool is used when you want to create a webhook subscription for event callbacks, but it does not explicitly contrast it with alternative webhook tools (list_webhooks, delete_webhook) or state when not to use it. Usage context is present but not fully explicit.

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

• get_messageA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the safe read nature is covered. The description adds behavioral context by mentioning 'current status', implying the status is dynamic and may change over time. This goes beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  The description is a single front-loaded sentence starting with the verb 'Retrieve', containing no redundant words. Every part contributes meaning: resource, scope, and criteria.

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

  Completeness4/5

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

  For a simple two-parameter retrieval tool with no output schema, the description adequately conveys the operation. It mentions the message ID requirement and current status retrieval. A minor gap is lack of return format details, but this is offset by the tool's low complexity.

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

  Parameters3/5

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

  Schema coverage is 100% with descriptions for both 'id' and 'channel'. The description restates these parameters ('by channel and ID') without adding new semantic details, so it provides no additional value beyond the schema.

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

  Purpose5/5

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

  The description uses the specific verb 'Retrieve', identifies the resource as 'previously sent message', and includes 'current status' scope. This clearly distinguishes it from sibling tools like list_messages (lists multiple messages) and send_* tools.

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

  Usage Guidelines3/5

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

  Usage context is implied: the tool requires a channel and message ID, indicating it is meant for retrieving a specific message after sending. However, it does not explicitly compare with alternatives like list_messages or state when not to use it, leaving the guidance implicit.

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

• list_endpointsA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that the tool returns a list of endpoints with path, method, and summary, but does not disclose pagination, sorting, or error behavior. Since the annotations cover the most critical behavioral aspect (no side effects), a score of 3 is appropriate.

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

  Conciseness5/5

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

  The description is two sentences long, directly states the purpose, and includes a necessary usage hint. No fluff or redundant information. It is front-loaded with the primary action and resource.

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

  Completeness4/5

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

  For a simple list tool with one parameter, no output schema, and safety annotations, the description is sufficiently complete. It covers the input source (spec) and the output shape (path + method + summary). The only minor omission is what happens if the spec title is invalid, but that is not critical for this complexity level.

  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 for the 'spec' parameter includes an explicit example ('Transmit Message API' or 'Transmit SMS API'), which provides good semantics. Since schema coverage is 100%, the description does not need to add much; however, it could have reinforced the relationship to list_specs, which it does implicitly in the description.

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

  Purpose5/5

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

  The description clearly states the action ('List all endpoints'), the resource ('for a given Kudosity API spec'), and the output contents ('path + method + summary'). It distinguishes this from sibling tools like list_specs (which lists specs) and get_endpoint (which fetches a specific endpoint), making the tool's role unambiguous.

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

  Usage Guidelines4/5

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

  The description explicitly instructs to 'Use list_specs first to get spec titles,' which is a valuable prerequisite hint. It does not explicitly mention when not to use this tool or name alternatives like search_endpoints, but the context is clear enough for an agent to make a sensible choice.

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

• list_messagesA
  4/5.0
  Behavior3/5

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

  Annotations already set readOnlyHint=true and openWorldHint=true, which covers safety. The description adds minimal behavioral context (e.g., that messages have delivery status) but doesn't disclose pagination, defaults, or any side-effect caveats. With annotations present, the description's contribution is limited but not contradictory.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action, and each sentence earns its place. It efficiently covers purpose, filters, and context without any fluff.

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

  Completeness4/5

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

  Given the high schema coverage and read-only nature, the description is adequate. It explains the delivery-report/reply focus, but slightly lacks mention of channel limitations (e.g., MMS not supported) which is handled in the schema, so not a major gap.

  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, so each parameter is well-documented. The description repeats filter categories (status, recipient, direction, date range) and clarifies OUT/IN semantics, but this adds little beyond the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'List sent or received messages with their delivery status,' specifying the verb, resource, and scope. It distinguishes from sibling tools like get_message (singular) and send_sms by framing this as the list view for delivery reports and replies.

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

  Usage Guidelines4/5

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

  The description provides clear context by calling it the 'delivery-report and reply view,' indicating when to use it. However, it does not explicitly mention alternatives or exclusions (e.g., use get_message for single message or MMS), so it stops short of explicit when-not guidance.

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

• list_webhooksA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 'all' scope and 'on your account' context, but does not disclose pagination or return format. This is consistent with annotations and adds some value, but not rich behavioral 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 concise sentence of seven words. It communicates the tool's purpose without any fluff or repetition.

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

  Completeness4/5

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

  For a simple list operation with no parameters and no output schema, the description is sufficiently complete. It tells the agent exactly what the tool does. Lack of return format details is a minor gap but not critical for such a straightforward tool.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema coverage is trivially 100%. The description does not need to explain any parameter semantics. Baseline for 0 params is 4, and the description adds no misleading information.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('webhooks') with scope ('all configured on your account'). It clearly distinguishes the tool from siblings like create_webhook and delete_webhook, and from list_endpoints, which deals with a different resource.

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

  Usage Guidelines3/5

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

  The description implies usage for viewing webhooks but does not provide explicit guidance on when to use this tool versus alternatives such as list_endpoints. No exclusions or alternative recommendations are mentioned.

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

• remove_contact_from_listA
  4/5.0
  Behavior4/5

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

  The description adds the auth requirement (KUDOSITY_API_SECRET) and the all-lists behavior beyond the annotations' destructiveHint, giving useful operational context not present in the annotations.

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

  Conciseness5/5

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

  The description is one concise sentence that front-loads the action and includes key details (special case and auth) without any extraneous information.

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

  Completeness4/5

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

  Given the simple tool with annotations covering safety and schema covering parameters, the description provides adequate context, including auth and the special list_id behavior. It omits return behavior, but that is acceptable without an output 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 already documents all parameters with 100% coverage, including the list_id=0 special case. The description repeats this but does not add significant new parameter semantics beyond the schema.

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

  Purpose5/5

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

  The description uses the specific verb 'Remove' with the resource 'contact from a list' and clarifies the special list_id=0 behavior, distinguishing it from sibling tools like add_contact_to_list and delete_list.

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

  Usage Guidelines3/5

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

  The description provides context about the auth requirement and the list_id=0 semantics, but does not explicitly compare to alternatives like add_contact_to_list or delete_list, so when-to-use guidance is implied rather than explicit.

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

• send_whatsappA
  4.1/5.0
  Behavior4/5

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

  Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds key operational constraints: the 24-hour window for free-form texts and the requirement for pre-approved templates. These are not captured in annotations. It doesn't mention return values or failure behavior, but the added constraints are significant.

  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, well-structured sentence that front-loads the primary action and packs the key constraints into a compact, readable format. No wasted words or redundant details.

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

  Completeness3/5

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

  With no output schema, the description does not explain what the API returns (e.g., a message ID). It also omits explicit failure conditions, though the 24-hour window constraint implies one. For a tool with 8 parameters and conditional requirements, the description is adequate but not fully complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are fully documented in the schema. The description adds no additional parameter semantics beyond the schema, including the text vs. template distinction which is already captured in the content_type enum. Baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states 'Send a WhatsApp message via Kudosity' with a specific verb and resource. It distinguishes between free-form text and pre-approved templates, and the channel is explicit, separating it from siblings like send_sms and send_mms.

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

  Usage Guidelines4/5

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

  The description provides explicit usage context: free-form text is only allowed within an open 24-hour customer-service window, while templates are sendable anytime. It does not explicitly name alternatives (e.g., send_sms) but the channel and constraints make the intended use clear.

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

• get_listsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare read-only and open-world hints, and the description adds the requirement 'Requires KUDOSITY_API_SECRET (v1 auth)', which informs the agent of necessary authentication. It also scopes the operation to 'your account', providing context. No side effects or destructive actions are mentioned, which is consistent with the read-only annotation.

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

  Conciseness5/5

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

  The description is exactly two sentences, front-loading the action ('List all contact lists on your account') followed by the auth requirement. No redundant information is included, and it is appropriately concise.

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

  Completeness4/5

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

  Given the tool's simplicity (0 parameters, read-only, no output schema), the description covers the essential purpose and authentication. It does not mention pagination or return format, but this is not critical for a list-all operation with no parameters. The sibling 'get_list' could have been referenced for distinction, but the plural name and 'all' provide sufficient context.

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

  Parameters4/5

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

  The input schema has zero parameters, so schema description coverage is 100%. The baseline for 0-parameter tools is 4, and the description adds no extra parameter semantics because none exist. The phrase 'all contact lists' implies no filtering, which aligns with the empty schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'List all contact lists on your account', using a specific verb and resource. It distinguishes from the sibling 'get_list' by explicitly saying 'all', indicating batch listing versus singular retrieval.

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

  Usage Guidelines3/5

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

  The description implies usage by stating it lists all contact lists, but does not explicitly provide when-to-use or alternatives like 'use get_list for a single list'. No exclusions or when-not-to-use are given, so usage guidance is inferred from the wording.

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

• list_specsA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that the output includes API specifications and endpoint counts, which is useful behavioral context, but it doesn't disclose additional traits like pagination or auth requirements. This is acceptable for a simple read-only list tool.

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

  Conciseness5/5

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

  The description is two sentences, immediately front-loading the purpose and then offering a use case. Every word is purposeful; no filler.

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

  Completeness4/5

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

  For a zero-parameter, read-only list tool, the description sufficiently covers what it does and when to use it. It omits an explicit return format, but 'how many endpoints each has' gives a reasonable expectation of the output. The availability of sibling tools and annotations further contextualize the tool.

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

  Parameters4/5

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

  The tool accepts no parameters (empty schema), so there is no parameter detail to document. The baseline score of 4 applies because there are zero parameters.

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

  Purpose5/5

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

  The description states a specific action: 'List the available Kudosity API specifications and how many endpoints each has.' This clearly identifies the tool as listing API specs, not actual endpoints, distinguishing it from sibling tools like list_endpoints.

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

  Usage Guidelines4/5

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

  The second sentence 'Use this to see what the Kudosity platform can do beyond the built-in tools' provides clear context for when to invoke this tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full exclusion-based guidance.

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

• get_endpointA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is known. The description adds context about what details are returned (description, parameters, request body schema, auth), but does not go further into behaviors like error handling or response format. This is acceptable given the annotations cover the safety profile.

  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, well-structured sentence that front-loads the main action and outcome, followed by succinct usage guidance. Every part serves a purpose with no wasted words.

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

  Completeness5/5

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

  For a simple read-only tool with 3 fully described parameters and no output schema, the description is complete. It states what the tool does, what it returns, and how to use it in sequence with related tools. No critical information is missing.

  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 each parameter (path, spec, method) having a clear meaning and example. The description does not add any extra parameter semantics, so the baseline of 3 applies since the schema carries the heavy lifting.

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

  Purpose5/5

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

  The description uses a specific verb ('Get') and resource ('one Kudosity API endpoint') and clearly enumerates what is returned (description, parameters, request body schema, auth). This distinguishes it from sibling tools like list_endpoints (which lists endpoints) and search_endpoints (which searches for them).

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

  Usage Guidelines5/5

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

  The description explicitly states 'Use search_endpoints or list_endpoints first', providing clear guidance on when this tool should be used relative to alternatives. This directs the agent to first find/identify an endpoint, then retrieve its full details, which is a clear workflow.

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

• search_endpointsA
  4.3/5.0
  Behavior4/5

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

  The description adds behavioral context by explaining what is searched ('across paths, summaries, descriptions, tags and parameters'). The annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description does not mention pagination or result format, but the added search-scope detail provides meaningful transparency beyond the annotations.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the action and resource. The second sentence reinforces the tool's purpose without redundant detail. Every word earns its place.

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

  Completeness5/5

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

  This is a straightforward search/discovery tool with two parameters, a readOnlyHint annotation, and no output schema. The description plus schema and annotations fully cover the necessary context: what it does, when to use it, and safe execution. No additional behavioral detail is required for correct invocation.

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

  Parameters3/5

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

  The input schema already provides complete descriptions for both parameters (query and spec), with examples for query like 'delivery', 'opt out', 'balance'. The tool description does not add additional parameter-level meaning beyond what the schema covers. With 100% 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.

  Purpose5/5

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

  The description uses specific verb 'Search' with a clear resource ('Kudosity API endpoints') and defines the scope across 'paths, summaries, descriptions, tags and parameters'. This distinguishes it from siblings like list_endpoints (which likely lists all) and get_endpoint (which retrieves a specific endpoint).

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

  Usage Guidelines4/5

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

  The description provides a clear use case: 'Use this to discover what the API can do.' This implies when to use the tool, but it does not explicitly state when not to use it or mention alternatives. The guidance is sufficient for an agent to select it for keyword-based discovery, but lacks the explicit exclusions of the top-tier example.

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

• get_balanceA
  4.4/5.0
  Behavior4/5

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

  The readOnlyHint and openWorldHint annotations already convey safety and open-world behavior. The description adds value by disclosing the authentication requirement (KUDOSITY_API_SECRET v1 Basic auth), which is useful beyond the annotations.

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

  Conciseness5/5

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

  The description is two short, efficient sentences. It states the core purpose and a necessary prerequisite without any filler or repetition.

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

  Completeness4/5

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

  For a simple, parameterless, read-only balance lookup, the description adequately covers purpose and auth. Not describing the response format is a minor gap, but the tool's simplicity and annotations make the description sufficient.

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

  Parameters4/5

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

  There are zero parameters, so the schema fully covers the absence of inputs. The description appropriately does not invent parameter details, and the baseline for 0 params is 4.

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

  Purpose5/5

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

  The description clearly states the tool retrieves the Kudosity account balance, using a specific verb 'get' and a distinct resource. It stands out from sibling tools focused on contacts, messages, webhooks, etc.

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

  Usage Guidelines4/5

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

  The description provides clear context by mentioning the required KUDOSITY_API_SECRET for Basic auth, which is a key prerequisite. It does not explicitly contrast with alternatives, but for a simple balance lookup, the intended use is evident.

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