Server Quality Checklist

Tool Scores

• plunk_verify_emailB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it only states what the tool does, not whether it is a read-only operation, if it sends network requests, or if it has side effects. The agent is left without important behavioral context.

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

  Conciseness5/5

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

  The description is a single sentence that is direct and front-loaded. It contains no fluff or unnecessary detail, making it appropriately concise for the tool's simplicity.

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

  Completeness3/5

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

  The tool is simple (one parameter, no output schema), but the description does not explain what the validation returns (e.g., boolean, detailed report). It also lacks usage context. While it is not egregiously incomplete for a simple tool, it leaves the agent guessing about the response format.

  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 one parameter with 100% schema description coverage. The tool description adds no additional meaning beyond the schema, but the schema itself is clear ('Email address to validate'). Hence, 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 'Validate that an email address is deliverable' clearly states the tool's action (validate) and resource (email address). It is specific and distinguishes itself from sibling tools like send or create, which perform different operations.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or alternative tools, leaving the agent to infer usage from the tool's name alone.

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

• plunk_delete_contactA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of explaining behavioral implications. It only restates the action without disclosing consequences such as irreversibility, effects on related data, or any special permissions needed. This is a minimal disclosure.

  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 with no redundant words. It front-loads the essential action and identifier, making it highly efficient.

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

  Completeness3/5

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

  For a simple delete-by-ID tool with one parameter and no output schema, the description states the core action. However, it omits any reassurance about return values or consequences of deletion, which could be useful given the lack of annotations and output schema. It is minimally complete but lacks contextual depth.

  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 the single parameter 'id' as 'Contact UUID' with 100% coverage. The description adds no extra semantic value beyond what the schema provides, so the baseline score 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 uses a specific verb ('Delete') and resource ('contact') with the identifier method ('by UUID'), clearly distinguishing it from sibling tools like get_contact, create_contact, or update_contact.

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

  Usage Guidelines3/5

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

  The description implies usage when you need to remove a contact, but it does not explicitly provide context such as when to prefer delete over unsubscribe or mention any prerequisites. This is implied rather than clearly stated.

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

• plunk_get_contactA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description must fully convey behavioral traits. It merely states 'Get a single contact by UUID' without adding any details such as read-only confirmation, return format, error behavior, or what happens if the contact does not exist. The description adds no transparent context beyond what the name and schema already imply.

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

  Conciseness5/5

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

  The description is a single, concise sentence that is front-loaded with the action and resource. Every word is necessary, with no redundant or tangential content.

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

  Completeness3/5

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

  The tool is simple (one parameter) but has no output schema or annotations. The description does not explicitly state the return value or not-found behavior. While 'Get' implies the contact object is returned, the lack of explicit return/error information leaves moderate gaps for a complete context.

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

  Parameters3/5

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

  The schema description covers 100% of the parameters, with 'id' described as 'Contact UUID'. The tool description restates this in prose ('by UUID') but does not add further semantic detail. Baseline score of 3 is appropriate since the 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 uses the specific verb 'Get' with the resource 'single contact' and the key parameter 'by UUID'. This clearly distinguishes the tool from siblings like list_contacts (which retrieves multiple), create_contact, and delete_contact, as it unambiguously targets a single contact lookup.

  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 for retrieving one specific contact by UUID, but it does not explicitly state when to use this tool instead of alternatives like list_contacts. No exclusions or alternative tool names are mentioned, leaving the usage context inferred from the purpose.

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

• plunk_create_contactA
  3.7/5.0
  Behavior3/5

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

  Without annotations, the description carries the full transparency burden. It usefully discloses server-side email normalization, which is a genuine behavioral detail beyond what the schema provides. However, it does not address output/return behavior, error conditions, or the full effect of upserting on existing contact fields.

  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 with no wasted words. The primary action is front-loaded, and the secondary normalization detail is relevant and concisely stated.

  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 create/upsert tool with no output schema and no annotations, this description is reasonably clear but incomplete. It explains the upsert-by-email concept and a normalization nuance, yet lacks details on return values, default subscription state, or error handling. It is adequate for a minimal use case but leaves gaps for nontrivial usage.

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

  Parameters3/5

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

  Schema description coverage is low (only 1 of 3 params described). The description adds valuable semantics for the email parameter by explaining normalization, but says nothing about 'data' or 'subscribed'. It partially compensates but leaves two parameters unexplained.

  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 action ('Create or upsert a contact by email'), which is specific and distinguishes it from sibling tools like get_contact or delete_contact. It also indicates the identity key (email), making the upsert semantics explicit.

  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 phrase 'Create or upsert' implies when to use this tool (for new contacts or updating existing ones by email), but it does not explicitly contrast this with update_contact or mention when not to use it. The context is clear but lacks explicit exclusions or alternatives.

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

• plunk_send_transactionalA
  3.8/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions the two modes of operation but doesn't disclose any consequences, permissions, error behavior, or the meaning of parameters like 'subscribed'. For a mutation action like sending an email, this is a significant gap.

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

  Conciseness5/5

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

  The description is extremely concise: two sentences, front-loaded with the primary action, and no wasted words. It earns its place by conveying the essential usage pattern.

  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?

  Despite having 11 parameters, nested objects, and no output schema, the description is only two sentences. It doesn't mention return values, error handling, or the role of parameters like subscribed, headers, or reply. For a complex tool, this is incomplete and leaves the agent without crucial 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?

  Schema descriptions cover 64% of parameters, but the description adds meaningful semantics by specifying the 'subject+body OR template UUID' relationship, which is not obvious from the schema alone. It clarifies the mutual exclusivity and reduces ambiguity. However, it doesn't explain undocumented parameters like reply, headers, or subscribed.

  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 exactly what the tool does: 'Send a transactional email.' It uses a specific verb and resource, and clearly distinguishes this from sibling tools like contact management and tracking tools. The subject+body OR template detail further clarifies the 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 provides clear guidance on how to use the tool: provide subject+body or a template UUID. It doesn't explicitly mention alternatives or when not to use it, but among siblings this is the only email-sending tool, and the instruction is sufficient for basic usage.

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

• plunk_list_contactsA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It mentions cursor pagination, case-insensitive email search, subscription filter, and column sort, plus version-specific constraints. It does not describe response format or permissions, but for a list tool, this is substantial.

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

  Conciseness5/5

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

  Two sentences provide purpose, features, and version constraints in a front-loaded structure with no 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?

  The tool has 7 parameters and no output schema or annotations, so the description needs to be substantial. It covers pagination, filtering, search, sorting, and version requirements, but does not describe the response shape or any required authentication. Still, it is reasonably complete for a list operation.

  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 high (86%), so the baseline is 3. The description adds version constraints for `subscribed`, `sort`, and `dir`, but mostly duplicates schema descriptions for search and sort. No new parameter semantics beyond what the schema provides.

  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 'List contacts' with a specific verb and resource, and lists key features like pagination, search, and filtering. This clearly differentiates it from sibling tools like plunk_get_contact (single contact) and plunk_create_contact.

  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 clear context for the tool's purpose but does not explicitly state when to use it instead of alternatives like plunk_get_contact. It does include version requirements that signal when certain features are available, but no exclusionary guidance.

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

• plunk_unsubscribe_contactA
  4/5.0
  Behavior2/5

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

  No annotations are present, so the description must disclose behavioral traits. It only states the action and the id type, but doesn't mention side effects, idempotency, errors, permissions, or what happens if the contact is already unsubscribed. The public id explanation is useful context but doesn't reveal behavior beyond the verb 'unsubscribe'.

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

  Conciseness5/5

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

  Two sentences, front-loaded with purpose, and the alternative guidance earns its place. No wasted 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 one-parameter action, purpose and parameter semantics are well covered. The description lacks return value or error behavior, but with no output schema and a simple action, it is still largely complete. Minor gap for a fully self-contained tool.

  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%, and the single parameter is richly described: public id, distinction from regular UUID, and how to obtain it. The description adds no parameter semantics beyond the schema, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description starts with a specific verb+resource: 'Unsubscribe a contact via their public id.' It clearly distinguishes itself from the batch unsubscribe alternative by explicitly naming plunk_bulk_unsubscribe_contacts.

  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 provides when-not-to-use guidance: 'For batch unsubscribes by regular id, use plunk_bulk_unsubscribe_contacts.' This makes the tool's scope versus its alternative clear.

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

• plunk_update_contactA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It reveals key edge cases: email uniqueness returns 409, and the data object has special semantics (null deletes, empty strings ignored, reserved keys filtered). However, it does not mention response formats or error cases like a non-existent contact, leaving some gaps.

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

  Conciseness5/5

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

  Three sentences, each providing distinct value: the action, email conflict behavior, and data object rules. No filler or redundancy; information is front-loaded with the purpose first.

  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?

  The description covers important operational details (HTTP method, conflict behavior, data handling) for an update tool with a nested object and no annotations or output schema. It is not fully exhaustive—missing return value and missing-contact error—but it is complete enough for an agent to select and invoke the tool correctly in most cases.

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

  Parameters3/5

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

  The description explains the email parameter ('Pass email to change the address') and the data object semantics, but it leaves 'subscribed' undescribed and relies on id being self-evident. Given the schema description coverage is 0%, this partial compensation is insufficient for full parameter understanding, though it adds meaningful context 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: 'Update fields on an existing contact (PATCH).' This is a specific verb+resource pair, and it distinguishes the tool from siblings like create, delete, and list. The additional mention of email and data behavior further clarifies its scope.

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

  Usage Guidelines3/5

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

  The description implies usage when an existing contact needs modification, but it does not explicitly compare to alternatives such as subscribe_contact or unsubscribe_contact, which also affect contact fields. There are no clear exclusion criteria or alternative tool references, though the context of 'existing contact' gives implicit guidance.

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

• plunk_track_eventA
  4.2/5.0
  Behavior4/5

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

  With no annotations present, the description carries the full burden. It discloses that contacts are auto-created if missing and explains that the endpoint is gated by the public key, not the secret key. This is valuable beyond the schema, though it doesn't mention response behavior or idempotency.

  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 action and key side effect. It then adds the purpose and the authentication nuance. Every sentence earns its place with no redundancy.

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

  Completeness4/5

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

  Given no annotations and no output schema, the description provides key contextual details: purpose, auto-creation, and the public key requirement. It could optionally mention response or error behavior, but it is sufficiently complete for an agent to choose and invoke this tool.

  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 for all parameters. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline score 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 opens with a specific verb and resource: 'Track an event for a contact (creates the contact if missing).' This clearly distinguishes it from sibling tools like send_transactional or verify_email. The purpose is 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?

  It states the tool is used to drive workflows and segment filters, and it explains the authentication requirement (public key vs. secret key). This provides clear context, though it doesn't explicitly name alternatives or when not to use the tool.

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

• plunk_subscribe_contactA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the disclosure burden. It adds critical behavioral context about the correct id type (public id embedded in unsubscribe links, not UUID), which is essential for correct invocation. However, it does not mention side effects like idempotency or error conditions, so it's not fully transparent but still informative.

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

  Conciseness5/5

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

  Two sentences with no redundancy. The primary action and the key distinction (public id vs UUID) are front-loaded, and the alternative is mentioned concisely.

  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?

  The tool is simple with one parameter and no output schema. The description covers the purpose, the critical id distinction, and the alternative for batch. It doesn't mention potential idempotency or response, but for a straightforward subscribe operation, this is sufficient. It is reasonably complete given the tool's simplicity.

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

  Parameters3/5

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

  The schema already provides 100% coverage of the single parameter, including a detailed description of the public id and how to obtain it. The description adds no new parameter semantics beyond what the schema already states, so it meets the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool subscribes a contact via their public id, which is specific and distinct from other sibling tools like plunk_create_contact or plunk_unsubscribe_contact. It also explicitly notes the id type (public, not UUID) and references the batch alternative, 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 Guidelines5/5

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

  The description explicitly directs users to use plunk_bulk_subscribe_contacts for batch subscribes by regular id, providing clear when-to-use guidance. It also implies this tool is for a single subscribe using the public id, effectively distinguishing it from bulk operations.

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

• plunk_upload_imageA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden and does well: it discloses the JSON shim behavior and the mismatch with the underlying multipart endpoint. It doesn't mention return values or error handling, but the key caveat is transparently surfaced.

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

  Conciseness5/5

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

  Two sentences: the first states purpose and usage, the second adds a necessary caveat. Nothing is wasted, and the most important information is front-loaded.

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

  Completeness4/5

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

  For a tool with no output schema and no annotations, the description covers the essential semantics: what the tool does, how to pass the image, and a potential compatibility issue. It doesn't explain post-upload behavior or response format, but the core context is well covered.

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

  Parameters4/5

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

  The schema already covers content and contentType, but the description adds the crucial detail that 'content' must be base64-encoded. The filename parameter is left without description, but the added base64 context improves understanding beyond the raw 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 uploads an image and gives a concrete use case ('for use in templates or campaigns'). It uses a specific verb ('Upload') and resource, distinguishing it from sibling tools like contact management or sending.

  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?

  It provides explicit how-to guidance ('Pass the file as base64') and an alternative ('if your Plunk version requires multipart, use the dashboard upload flow'). This clarifies when to use this tool versus the alternative, and even highlights a compatibility caveat.

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