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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes the operation's purpose, provides a usage scenario, and discloses the return format ('{ added: number } or similar success indicator'). However, it doesn't mention potential side effects, error conditions, or permission requirements that might be relevant for a mutation operation.

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

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

The description is efficiently structured with four distinct, purposeful sentences: purpose statement, usage guidelines, return value disclosure, and parameter example. Each sentence adds unique value with zero redundancy, and the most critical information (what the tool does) is front-loaded in the first sentence.

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

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

For a mutation tool with no annotations and no output schema, the description provides good coverage: clear purpose, usage context, return format, and parameter example. However, it lacks details about error handling, idempotency, or what happens when adding contacts that are already in the segment, which would be helpful for a tool that modifies data.

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

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

The schema description coverage is 100%, so the schema already documents both parameters ('Segment ID' and 'Contact IDs to add'). The description adds minimal value beyond the schema by providing an example parameter structure, but doesn't explain format requirements, constraints, or relationships between parameters that aren't already in the schema descriptions.

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

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

The description clearly states the specific action ('Add'), resource ('contacts'), and target ('to a segment') in the first sentence. It distinguishes from sibling tools like 'remove_contact_from_segment' by specifying the opposite operation, and from 'create_segment' by focusing on adding contacts to existing segments rather than creating new ones.

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

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

The 'When to use' section explicitly provides usage context: 'enroll specific contacts in an existing segment' and gives a concrete example scenario ('agent built a list and wants to materialise it'). This clearly distinguishes when to use this tool versus alternatives like 'create_segment' for new segments or 'update_segment' for modifying segment properties.

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

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

With no annotations provided, the description carries full burden and does well by explaining the tool's effect ('Block... from receiving any future sends') and return format ('shaped suppression record'). It could improve by mentioning potential side effects (e.g., whether this affects existing emails) or permission requirements, but covers core behavior adequately.

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

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

The description is perfectly structured: purpose statement first, usage guidelines second, return information third, and an example fourth. Every sentence adds value with zero wasted words, making it easy to scan and understand quickly.

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

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

For a mutation tool with no annotations and no output schema, the description does well by explaining the action, when to use it, and what it returns. It could be more complete by explicitly stating this is a write operation or mentioning any constraints, but it provides sufficient context for effective use.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema - it provides an example showing parameter usage but doesn't explain semantics beyond what's in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Block an email address') and resource ('from receiving any future sends'), distinguishing it from siblings like 'remove_suppression' or 'list_suppressions'. It uses precise terminology that conveys the tool's exact function.

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

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

The description explicitly provides when-to-use guidance: 'a recipient asked to be removed (manual), or you're importing prior bounces/complaints.' This gives concrete scenarios for application, helping differentiate from other suppression-related tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's dual-mode behavior, return formats for both modes, and sorting behavior ('sorted by metric desc'). However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions that would be helpful for complete transparency.

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

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

The description is efficiently structured with zero wasted sentences. It front-loads the purpose, immediately follows with usage guidelines, then provides return format details, and concludes with practical examples. Every sentence serves a distinct purpose: mode explanation, usage guidance, output specification, and parameter illustration.

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

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

For a tool with 4 parameters, no annotations, and no output schema, the description does an excellent job covering operational behavior, return formats, and parameter semantics. The only minor gap is the lack of explicit mention about default values (though implied in examples) and potential error cases. Given the complexity of dual-mode operation, the description is nearly complete for agent understanding.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the semantic relationship between parameters - specifically how 'broadcast_id' triggers single mode while 'since' and 'best_metric' trigger leaderboard mode. It provides concrete examples showing parameter combinations, which helps the agent understand the mutually exclusive usage patterns beyond what the schema provides.

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

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

The description clearly states the tool's purpose with specific verbs ('Get broadcast performance') and distinguishes between two distinct modes (single broadcast analysis vs. leaderboard ranking). It explicitly differentiates from sibling tools like 'get_broadcast' (which likely retrieves metadata) by focusing on performance metrics and ranking capabilities.

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

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

The description provides explicit guidance on when to use this tool ('agent wants to find the best-performing broadcast in a date range, or drill into one broadcast's stats') and clearly distinguishes between the two operational modes with parameter-based instructions. It offers practical examples for both modes, making it easy for an agent to select the appropriate usage scenario.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's destructive nature ('cancel'), operational constraints ('queued or sending' only, not delivered), and return format ('{ success: boolean }'), though it doesn't mention permissions, rate limits, or error conditions.

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

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

The description is efficiently structured with four concise sentences: purpose statement, usage guidance, return format, and example. Every sentence adds value without redundancy, and key information is front-loaded appropriately.

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

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

For a single-parameter mutation tool with no annotations and no output schema, the description provides good coverage: clear purpose, usage boundaries, behavioral constraints, and return format. It could be more complete by mentioning authentication requirements or error cases, but it's substantially adequate.

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

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

Schema description coverage is 100%, so the schema already documents the single 'id' parameter. The description adds minimal value beyond the schema by providing an example ('{ id: "br_abc" }') but doesn't explain parameter semantics further. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('Cancel') and target resource ('a queued or sending broadcast'), distinguishing it from sibling tools like 'update_broadcast' or 'get_broadcast'. It precisely defines the operation's scope without being tautological.

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

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

The description explicitly provides when-to-use guidance ('stop a broadcast mid-flight') and a critical exclusion ('Already-delivered messages cannot be recalled'), helping the agent choose this tool over alternatives like 'update_broadcast' or 'reschedule_email' for cancellation scenarios.

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

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

With no annotations provided, the description carries full burden and does well by specifying the precondition ('scheduled email that has not yet entered the sending pipeline'), the limitation ('Cannot cancel emails already delivered'), and the return format ('{ success: boolean }'). It doesn't mention error conditions or authentication requirements, but provides substantial behavioral context for a single-parameter tool.

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

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

Perfectly structured with four distinct, purposeful sentences: purpose statement, usage guidance, return format, and example. Each sentence adds unique value with zero redundancy. The description is appropriately sized and front-loaded with the most critical information.

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

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

For a single-parameter mutation tool with no annotations and no output schema, the description provides everything needed: clear purpose, precise usage conditions, behavioral constraints, return format, and parameter example. It addresses the key concerns for a destructive operation (cancellation) without over-explaining simple concepts.

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

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

Schema description coverage is 100% with the parameter 'id' documented as 'Email ID to cancel.' The description adds value by providing an example format '{ id: "em_7kf2x9" }' which clarifies the expected parameter structure beyond the schema's basic type information. This compensates well for having only one parameter.

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

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

The description clearly states the specific action ('Cancel a scheduled email') and the resource ('email that has not yet entered the sending pipeline'), distinguishing it from siblings like 'cancel_broadcast' which operates on a different resource. It provides precise scope information that goes beyond just restating the tool name.

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

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

Explicitly states 'When to use: agent wants to recall a scheduled send before it goes out' and provides a clear exclusion 'Cannot cancel emails already delivered.' This gives perfect guidance on when this tool is appropriate versus when it won't work, addressing the key decision criteria for invocation.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a mutation operation ('Reset') and specifies the return format, but doesn't mention important behavioral aspects like authentication requirements, rate limits, whether the old password becomes invalid immediately, or potential side effects on connected email clients. The description adds some value but leaves significant gaps.

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

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

The description is efficiently structured with purpose statement, usage guidelines, return format, and example in just four lines. Each sentence serves a distinct purpose, though the example could be slightly more clearly formatted or labeled as such.

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

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

For a mutation tool with no annotations and no output schema, the description provides purpose, usage guidelines, and return format, but lacks important contextual information about authentication requirements, error conditions, or what happens to existing sessions. The example helps but doesn't fully compensate for the missing behavioral context that would be crucial for safe invocation.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing an example parameter structure '{ id: 17, password: "<new strong>" }' that illustrates proper usage, though it doesn't elaborate on password strength requirements or ID validation beyond what the schema already documents.

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

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

The description clearly states the specific action ('Reset a mailbox's IMAP/SMTP password') and identifies the resource ('mailbox'), making the purpose immediately apparent. It distinguishes this tool from sibling tools like 'update_mailbox' or 'create_mailbox' by focusing specifically on password reset functionality rather than general mailbox updates.

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

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

The description explicitly provides usage guidance with 'When to use: rotate after suspected exposure, or onboarding handoff.' This gives clear scenarios for when this tool should be invoked, helping the agent distinguish it from other password-related or mailbox management tools in the sibling list.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does: combines DNS verification, bounce/complaint rates, and deliverability warnings into one response. It also hints at the tool's read-only nature by using 'check' and not implying any modifications, though it doesn't explicitly state permissions or rate limits.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, return details, and an example. Every sentence adds essential information without redundancy, making it efficient and easy to parse.

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

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

Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is quite complete. It explains the purpose, usage, and return structure in detail. However, it lacks explicit mention of error handling or edge cases, which slightly reduces completeness.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value by providing an example parameter usage ('Example: { from: "Acme <hi@acme.io>" }'), which clarifies the expected format beyond the schema's generic description, earning a higher score.

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

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

The description explicitly states the tool's purpose: 'Check whether a from-address is safe to send from RIGHT NOW.' It specifies the verb ('check'), resource ('from-address'), and scope ('safe to send from'), clearly distinguishing it from sibling tools like 'verify_domain' or 'suggest_from_address' that serve different functions.

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

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

The description provides explicit guidance: 'When to use: BEFORE sending agent-generated content from a non-default domain.' This clearly indicates the timing ('BEFORE'), context ('agent-generated content'), and condition ('non-default domain'), helping users distinguish when to use this tool versus alternatives like 'send_email' or 'lint_email'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains critical behaviors: the key is returned only once and cannot be retrieved again, and the agent should display it once and advise secure storage. However, it doesn't mention potential side effects like rate limits, authentication requirements, or whether this operation is idempotent.

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

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

The description is efficiently structured with four sentences that each serve a distinct purpose: stating the action, warning about one-time retrieval, providing usage guidelines, and giving an example. There is no wasted verbiage, and key information is front-loaded.

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

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

For a mutation tool with no annotations and no output schema, the description does well by explaining the one-time nature of the response and security implications. However, it could be more complete by detailing the return format beyond 'shaped key' or mentioning error conditions, though the usage guidelines and behavioral notes partially compensate.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by providing an example with 'name' and 'permission' parameters, but doesn't explain 'mode' or 'domain_id' semantics further. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Generate a new PostStack API key') and resource ('API key'), distinguishing it from sibling tools like 'get_api_key' and 'list_api_keys' which retrieve existing keys rather than creating new ones. The verb 'Generate' is precise and unambiguous.

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

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

The description explicitly states 'When to use: agent needs to provision credentials for a new integration' and provides clear alternatives for the 'permission' parameter ('sending_access' for send-only keys vs. 'full_access' for management). It also recommends 'sending_access' for app servers, offering practical guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the broadcast is created in 'draft' status, requires subsequent 'send_broadcast' to dispatch, and returns a shaped broadcast with specific fields (id, subject, status=draft, recipient counts will populate on send). It doesn't mention permissions, rate limits, or error conditions, but covers the core workflow adequately.

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

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

The description is well-structured and concise, with four sentences that each add value: purpose statement, usage guidelines, behavioral context, and an example. There is no redundant or unnecessary information, making it efficient and easy to parse.

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

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

Given the tool's complexity (creation with 9 parameters) and lack of annotations or output schema, the description does a good job of covering essential context: purpose, usage, behavioral traits, and an example. It doesn't detail all parameters or error handling, but for a tool with high schema coverage, it provides sufficient guidance for effective use.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description adds minimal parameter semantics beyond the schema—it mentions 'segment_id', 'from', 'subject', and 'html' in the example but doesn't explain their roles or constraints further. This meets the baseline of 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose with specific verb+resource: 'Create a draft broadcast targeted at a segment.' It distinguishes from siblings like 'send_broadcast' by specifying it creates a draft, not a sent broadcast, and from 'update_broadcast' by focusing on creation rather than modification.

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

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

The description provides explicit usage guidance: 'When to use: agent has assembled a campaign body + segment id and wants to stage it for review or scheduled send.' It also specifies the alternative action: 'call send_broadcast to dispatch,' clearly differentiating when to use this tool versus its sibling.

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

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

With no annotations provided, the description carries full burden and does well by specifying the return format ('shaped contact (id, email, names, properties, createdAt)') and providing an example. It doesn't mention permissions, rate limits, or error conditions, but covers core behavior adequately.

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

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

Perfectly structured with purpose statement, usage guidelines, return specification, and example - all in four concise sentences with zero wasted words. Front-loaded with the core purpose.

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

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

For a creation tool with no annotations and no output schema, the description provides excellent context: clear purpose, usage guidelines, return format, and example. It doesn't cover error cases or system limits, but is quite complete for practical use.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add parameter-specific information beyond what's in the schema, but the example illustrates usage of email, first_name, and properties parameters.

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

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

The description clearly states the verb ('Create') and resource ('new contact'), with additional context about what a contact represents ('person who can receive emails / broadcasts'). It distinguishes from sibling tools like 'update_contact' by focusing on creation rather than modification.

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

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

Explicitly provides when-to-use guidance ('ingest a new signup, programmatic enrollment, or one-off addition') and when-not-to-use alternatives ('For bulk imports prefer the API import endpoint'), clearly differentiating from bulk operations.

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

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

No annotations are provided, so the description carries full burden. It states the tool 'Define[s] a custom contact property' and mentions it 'Returns: shaped property definition', which implies a write operation with a structured output. However, it lacks details on permissions, side effects, or error conditions that would be important for a creation tool.

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

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

Well-structured with three sentences: purpose statement, usage guidelines, and an example. Each sentence earns its place by providing essential information without redundancy. The description is front-loaded with the core function and remains appropriately sized.

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

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

For a creation tool with no annotations and no output schema, the description does well by explaining purpose, usage, and providing an example return. However, it lacks details on behavioral aspects like permissions or error handling, which would be needed for full completeness given the tool's complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds minimal param semantics beyond the schema, only hinting at usage in the example. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't add significant value here.

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

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

The description clearly states the verb 'Define' and resource 'custom contact property', specifying it creates a typed schema for contact.properties. It distinguishes from siblings like list_contact_properties (reads) and delete_contact_property (removes), making the purpose specific and differentiated.

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

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

Explicitly provides 'When to use' guidance: 'agent is extending the contact data model — e.g. add a "plan" or "company" field that other tools can filter on.' This gives clear context for when this tool is appropriate versus alternatives like update_contact_property or list_contact_properties.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it creates a new domain, returns DNS records that require user configuration, and results in a 'pending status' until verification. However, it doesn't mention potential errors, rate limits, or authentication requirements.

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

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

The description is efficiently structured with three sentences: purpose, usage context, and return value. Each sentence adds essential information without redundancy, and it's appropriately front-loaded with the core functionality.

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

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

For a creation tool with 6 parameters, 100% schema coverage, and no output schema, the description provides good context about the tool's purpose, usage, and return behavior. However, it could be more complete by mentioning authentication needs or potential side effects, though the lack of annotations makes this less critical.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description provides an example with 'name' and 'region' but doesn't add meaningful semantic context beyond what the schema provides for any parameters, meeting the baseline expectation.

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

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

The description clearly states the specific action ('Add a new sending domain') and resource ('PostStack'), distinguishing it from sibling tools like 'get_domain', 'update_domain', 'delete_domain', and 'verify_domain'. It explicitly defines the tool's purpose beyond just the name.

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

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

The description provides explicit guidance on when to use this tool ('a customer is onboarding a new sending domain') and mentions the prerequisite DNS configuration needed before 'verify_domain' can succeed, clearly differentiating it from the sibling 'verify_domain' tool.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a creation/mutation operation (implied by 'provision'), requires domain verification as a prerequisite, and mentions the password is for IMAP/SMTP login. It could improve by mentioning rate limits or error conditions.

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

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

Front-loaded with the core purpose, followed by usage guidelines, return information, and an example - all in 4 concise sentences. Every sentence adds value with no redundancy or unnecessary information.

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

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

For a creation tool with no annotations and no output schema, the description does well by explaining what it returns ('shaped mailbox with emailAddress and quotaBytes') and providing an example. It could be more complete by mentioning error cases or what happens if the domain isn't verified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema - it mentions password is 'required for IMAP/SMTP login' and provides an example with specific parameter values, but doesn't explain parameter interactions or constraints beyond what's in the schema.

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

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

The description clearly states the specific action ('Provision a mailbox'), resource ('IMAP/SMTP inbox on a verified domain'), and distinguishes it from siblings like 'create_domain' or 'update_mailbox' by focusing on initial mailbox creation. It provides concrete examples of use cases like 'support@acme.io'.

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

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

Explicitly states when to use ('agent is setting up a real human-readable inbox') and includes prerequisites ('The domain must already be verified'). It distinguishes from alternatives by specifying this is for provisioning new mailboxes, not updating existing ones (which would use 'update_mailbox').

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

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

With no annotations provided, the description carries full burden and does well: it discloses this creates a 'static' segment (behavioral trait), specifies it's 'manually-managed' (management style), and describes the return value ('shaped segment with id and contactCount=0'). It doesn't mention permissions, rate limits, or idempotency, but covers key behavioral aspects.

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

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

Perfectly structured with four concise sentences: purpose statement, usage guidelines, return value, and example. Each sentence earns its place with zero waste, and key information is front-loaded.

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

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

For a creation tool with no annotations and no output schema, the description is quite complete: it explains purpose, usage, behavior, and return format. It could mention error conditions or prerequisites (e.g., authentication), but covers the essentials well given the context.

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

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

Schema description coverage is 100%, so the schema already documents the single 'name' parameter. The description adds minimal value beyond the schema with the example '{ name: "Spring 2026 launch" }', which illustrates usage but doesn't provide additional semantic context like naming constraints or character limits.

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

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

The description clearly states the tool's purpose with specific verb ('Create') and resource ('static contact segment'), and distinguishes it from siblings by specifying it's 'manually-managed' (unlike dynamic segments) and noting that members are added via a different tool ('add_contacts_to_segment').

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

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

Explicitly provides 'When to use' guidance ('agent needs a named bucket of contacts to send a broadcast to') and names an alternative tool for adding members ('Add members via add_contacts_to_segment'), giving clear context for when to use this tool versus others.

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

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

No annotations are provided, so the description carries full burden. It states this is a creation operation and mentions what it returns ('shaped topic'), but doesn't disclose important behavioral aspects like required permissions, whether this is idempotent, error conditions, or rate limits. The example helps but doesn't cover behavioral traits.

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

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

Perfectly structured with three distinct, purposeful sentences: purpose statement, usage guidelines, and return example. Every sentence adds value with zero waste. The description is appropriately sized and front-loaded with the most important information.

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

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

For a creation tool with no annotations and no output schema, the description does well by explaining purpose, usage context, and providing a return example. However, it lacks details about error conditions, permissions needed, or what 'shaped topic' means structurally. Given the complexity level, it's mostly complete but has minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds minimal param semantics beyond the schema - just an example showing typical values. With high schema coverage, baseline is 3, but the example provides some additional context, warranting a 4.

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

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

The description clearly states the verb 'Create' and resource 'subscription topic', with specific clarification that it's a 'named opt-in/opt-out preference like "Product Updates"'. It distinguishes from siblings like 'create_contact', 'create_segment', and 'create_template' by focusing specifically on subscription topics.

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

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

Explicitly provides 'When to use' guidance: 'agent is setting up granular preferences so contacts can subscribe per topic instead of all-or-nothing'. This gives clear context about when this tool should be selected over other preference-related tools, though it doesn't name specific alternatives.

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

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

With no annotations provided, the description carries full burden and does well: it discloses that templates are created unpublished, mentions the need for a separate publish step, and describes the return shape. It doesn't mention permissions, rate limits, or error conditions, but covers the essential behavioral traits.

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

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

Perfectly structured: purpose statement first, usage guidelines second, return information third, and example last. Every sentence earns its place with zero waste. The example is appropriately brief and illustrative.

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

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

For a creation tool with no annotations and no output schema, the description provides excellent context: purpose, usage guidelines, behavioral details (unpublished state), return shape, and an example. It doesn't cover all possible edge cases or error scenarios, but gives the agent enough to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema: it mentions '{{variable}} placeholders' generally and provides an example showing name, subject, and html usage. This adds some context but doesn't significantly enhance the already well-documented schema.

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

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

The description clearly states the verb ('Create') and resource ('new email template'), specifies it includes variable placeholders, and distinguishes from siblings like 'duplicate_template' and 'update_template' by focusing on initial creation. It's specific and unambiguous.

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

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

Explicitly states 'When to use: store a re-usable email body the agent (or app) will send repeatedly' and provides clear prerequisites: 'Newly created templates are unpublished — call publish_template before sending.' This gives perfect guidance on when and how to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the webhook receives 'signed POST requests' (security detail), returns a 'shaped webhook with id, url, events[], active=true' (output structure), and implies persistence (since it's a subscription). However, it doesn't mention rate limits, error handling, or authentication requirements beyond signing.

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

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

Highly efficient and front-loaded: first sentence states core purpose, second provides usage context, third describes returns, and fourth gives an example. Every sentence earns its place with no redundancy or fluff. The structure logically flows from what it does to when to use it to what it returns.

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

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

For a creation tool with no annotations and no output schema, the description does well: it explains purpose, usage, behavior, and provides an example. However, it lacks details on error conditions, idempotency, or how the webhook integrates with the system (e.g., confirmation process). Given the complexity, it's mostly complete but has minor gaps.

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

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

Schema description coverage is 100%, with both parameters (url, events) well-documented in the schema. The description adds minimal value beyond the schema: it implies 'url' is an endpoint URL (already in schema) and 'events' are for subscription (already in schema). The example provides concrete values but no additional semantic context. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose with specific verb ('Subscribe') and resource ('URL to receive event notifications'), and distinguishes it from siblings like 'delete_webhook' and 'update_webhook' by focusing on creation. It goes beyond the name 'create_webhook' by explaining what the webhook does (receives signed POST requests).

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

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

Explicitly provides a 'When to use' section that specifies the context: 'agent is configuring an integration that needs to react to email/contact/domain events in real time.' This gives clear guidance on when this tool is appropriate versus alternatives like polling or other event-handling methods.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates critical traits: the operation is 'permanent' and 'irreversible,' and it returns a success boolean. However, it doesn't mention potential side effects (e.g., impact on related data), error conditions, or permissions required, leaving some gaps in 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.

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

The description is front-loaded with the core action and key warning, followed by usage guidelines, return value, and an example—all in four concise sentences. Each sentence adds essential information without redundancy, making it highly efficient and well-structured for quick comprehension.

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

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

Given the tool's complexity (destructive operation with no annotations and no output schema), the description does a good job covering purpose, usage, and behavioral traits. It includes return value information, which compensates for the lack of output schema. However, it could be more complete by addressing permissions or error handling, slightly reducing the score.

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

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

The input schema has 100% description coverage, with the 'id' parameter fully documented in the schema. The description adds minimal value beyond the schema by providing an example ('{ id: "con_abc123" }'), but doesn't explain parameter semantics further. This meets the baseline of 3 since the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Permanently delete') and resource ('a contact'), distinguishing it from the sibling 'unsubscribe_contact' by emphasizing the irreversible nature. It explicitly contrasts with the alternative tool for opt-outs, making the purpose unambiguous and distinct.

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

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

The description provides explicit guidance on when to use this tool ('GDPR erasure or removing a test contact') and when not to ('For unsubscribes, prefer unsubscribe_contact which preserves history'). It names the alternative tool and explains the key difference (irreversible deletion vs. preserving history), offering clear decision criteria.

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

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

With no annotations provided, the description carries full burden and does well by disclosing destructive behavior ('Existing contact values for this property are dropped'), irreversibility ('values are not recoverable'), and return format ('Returns: { success: boolean }'). It doesn't mention permissions or rate limits, but covers key behavioral aspects.

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

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

Front-loaded with the core purpose, followed by critical warnings, return format, and an example—all in four efficient sentences with zero wasted words. Every sentence adds value to the agent's understanding.

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

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

For a destructive tool with no annotations and no output schema, the description provides strong context: purpose, usage guidelines, behavioral warnings, and return format. It could mention authentication needs or error cases, but covers the essentials well given the complexity.

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

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

Schema description coverage is 100% with the parameter 'id' well-documented as 'Property ID to delete'. The description doesn't add additional parameter semantics beyond what the schema provides, but the schema already does the heavy lifting, meeting the baseline for high coverage.

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

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

The description clearly states the specific action ('Remove a custom contact property definition') and resource ('custom contact property'), distinguishing it from siblings like 'delete_contact' or 'delete_domain'. It precisely defines what the tool does beyond just the name.

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

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

Explicitly provides when-to-use guidance ('a property is unused and being retired') and includes a critical warning to 'Confirm with the user — values are not recoverable.' This offers clear context for appropriate usage versus alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates critical behavioral traits: the operation is 'permanent' and 'irreversible,' clarifies that 'historical email records remain,' and warns about consequences ('future sends from any matching from-address will fail'). It also specifies the return format. The only minor gap is lack of explicit mention about permissions or rate limits.

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

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

The description is efficiently structured with four distinct, purposeful sentences: 1) states the action and its permanence, 2) provides usage context, 3) specifies return format, and 4) gives an example. Every sentence adds value with zero wasted words.

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

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

For a destructive operation with no annotations and no output schema, the description provides excellent context: it clearly explains the irreversible nature, when to use it, consequences, and return format. The only minor gap is that it doesn't explicitly mention authentication requirements or error conditions, but given the comprehensive coverage of the most critical aspects, this is still strong.

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

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

The schema description coverage is 100% with the single parameter 'id' well-documented as 'Domain ID to delete.' The description doesn't add any additional parameter semantics beyond what the schema provides, but with complete schema coverage, 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.

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

The description clearly states the specific action ('permanently delete') and resource ('a sending domain'), distinguishing it from sibling tools like 'delete_contact' or 'delete_template'. It also specifies the irreversible nature, which helps differentiate it from other deletion tools that might be reversible.

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

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

The description explicitly states 'When to use: a domain is being decommissioned' and provides important guidance to 'Confirm with the user first since future sends from any matching from-address will fail.' This gives clear context for when to use this tool versus alternatives like 'update_domain' or 'verify_domain'.

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

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

With no annotations provided, the description carries full burden and delivers excellent behavioral disclosure. It explicitly states the destructive nature ('IRREVERSIBLE — confirm with the user, mail is gone'), describes the return format ('Returns: { success: boolean }'), and provides an example parameter usage.

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

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

The description is perfectly structured with four concise sentences: purpose statement, usage context, warning, and return format. Each sentence earns its place with zero waste, and critical information is front-loaded.

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

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

For a destructive operation with no annotations and no output schema, the description provides complete context: clear purpose, usage guidelines, explicit behavioral warnings, return format, and parameter example. This fully compensates for the lack of structured metadata.

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

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

The schema description coverage is 100% with the single parameter 'id' well-documented. The description adds minimal parameter semantics beyond the schema through the example '{ id: 17 }', but doesn't provide additional context about valid ID ranges or constraints. Baseline 3 is appropriate given the comprehensive schema coverage.

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

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

The description explicitly states the action ('permanently delete') and resource ('a mailbox and all its stored mail'), making the purpose specific and clear. It distinguishes from siblings like 'delete_contact' or 'delete_domain' by specifying the mailbox resource.

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

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

The description provides explicit guidance on when to use ('decommissioning a mailbox') and includes a strong warning about irreversibility with a directive to 'confirm with the user'. This clearly establishes usage context and exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's a destructive operation ('Delete'), clarifies side effects ('Contacts in it are NOT deleted'), specifies the return format ('Returns: { success: boolean }'), and includes an example. However, it doesn't mention potential errors, permissions required, or irreversible consequences beyond the basic scope.

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

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

The description is highly concise and well-structured: four short sentences that each serve a distinct purpose (action definition, side effect clarification, usage guidance, return format, and example). There is no wasted text, and critical information is front-loaded.

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

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

For a destructive tool with no annotations and no output schema, the description does well by covering purpose, usage, side effects, and return format. However, it lacks details on error conditions, authentication requirements, or rate limits, which would be helpful given the tool's complexity and risk profile.

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

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

The input schema has 100% description coverage (the 'id' parameter is fully documented in the schema). The description adds minimal parameter semantics beyond the schema—it only provides an example ('Example: { id: "seg_abc" }') which reinforces but doesn't significantly expand on the schema's documentation. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Delete a segment definition') and resource ('segment'), distinguishing it from siblings like 'delete_contact' or 'delete_template'. It explicitly clarifies what is not affected ('Contacts in it are NOT deleted'), which helps differentiate its scope from other deletion tools.

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

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

The description provides explicit usage guidance: 'When to use: remove an obsolete segment. Confirm with the user.' This directly states the intended context (removing obsolete segments) and includes a critical behavioral instruction (user confirmation), which is essential for a destructive operation.

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

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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the operation is permanent ('Permanently delete'), has side effects ('Subscriptions are removed'), and returns a simple success indicator. However, it doesn't mention error conditions, permissions needed, or rate limits.

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

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

Extremely efficient and well-structured: purpose statement first, followed by usage guidance, return value, and example. Every sentence earns its place with zero wasted words. The information is front-loaded appropriately.

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

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

For a destructive mutation tool with no annotations and no output schema, the description does well by covering purpose, usage context, side effects, and return format. It could be more complete by mentioning error cases or authentication requirements, but it provides sufficient context for safe agent invocation.

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

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

Schema description coverage is 100% (the 'id' parameter is fully documented in the schema). The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 when schema does the heavy lifting.

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

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

The description clearly states the specific action ('Permanently delete') and resource ('a subscription topic'), and distinguishes it from siblings like 'create_subscription_topic' and 'list_subscription_topics'. The verb 'delete' is precise and unambiguous.

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

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

Explicitly provides when-to-use guidance ('a topic is being retired') and a critical prerequisite ('Confirm with the user'). This directly addresses agent decision-making for a destructive operation, distinguishing it from alternatives like 'unsubscribe_contact_from_topic'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the operation is 'permanent' and 'irreversible,' and it warns that emails referencing the template will fail. However, it doesn't mention potential side effects like audit logs, permissions required, or error handling, 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.

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

The description is well-structured and front-loaded, starting with the core action and critical warning. Each sentence adds value: the first states the irreversible nature, the second provides usage guidelines, the third specifies the return value, and the fourth gives an example. There is no wasted text, making it highly efficient.

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

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

Given the tool's complexity (destructive operation with no annotations and no output schema), the description is complete. It covers the purpose, usage guidelines, behavioral traits (irreversibility and impact on emails), and includes an example. While an output schema is absent, the description specifies the return format, ensuring adequate context for the agent.

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

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

The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'Template ID to delete.' The description adds minimal value beyond this, only implying the parameter in the example. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't significantly enhance parameter understanding.

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

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

The description explicitly states the action ('permanently delete') and resource ('a template'), making the purpose clear. It distinguishes from siblings like 'delete_template' vs 'unpublish_template' or 'duplicate_template' by emphasizing irreversible deletion, which is specific and helpful for differentiation.

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

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

The description provides explicit guidance: 'When to use: an unused template should be removed. Confirm with the user — emails referencing this template_id will fail.' This clearly states the appropriate context (unused templates), a prerequisite (user confirmation), and a consequence (email failures), offering comprehensive usage instructions.

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

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

No annotations are provided, so the description carries full burden. It effectively discloses key behavioral traits: the action is permanent ('Permanently delete'), has significant side effects ('events will no longer be delivered'), and requires user confirmation. However, it doesn't mention authentication needs, rate limits, or error conditions, 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.

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

Front-loaded with the core purpose, followed by usage guidance, return value, and an example—all in four concise sentences with zero waste. Each sentence earns its place by adding distinct value (action, context, output, illustration).

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

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

For a destructive tool with no annotations and no output schema, the description does well by explaining the permanent nature, when to use, and return format. It covers critical aspects like side effects and confirmation needs. However, it lacks details on authentication, error handling, or system constraints, which could be important for full context.

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

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

Schema description coverage is 100%, with the parameter 'id' fully documented in the schema as 'Webhook ID to delete'. The description adds minimal value beyond this, only providing an example '{ id: 17 }' which reinforces but doesn't significantly expand on schema information. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the specific action ('Permanently delete') and resource ('a webhook endpoint'), distinguishing it from sibling tools like 'delete_webhook' vs 'create_webhook', 'update_webhook', 'get_webhook', and 'list_webhooks'. The verb 'delete' is precise and unambiguous.

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

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

Explicitly provides when to use ('the integration is being removed') and includes a critical caution ('Confirm with the user — events will no longer be delivered'). This gives clear context for application and highlights irreversible consequences, guiding proper tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a heuristic that builds a skeleton with proper threading, quoted original, salutation/sign-off, and suggested fields, and returns a structured object. However, it doesn't mention potential limitations like error conditions or performance aspects.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, return details, and an example. Every sentence earns its place with no wasted words, making it efficient and easy to parse.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It explains purpose, usage, returns, and provides an example. However, without an output schema, it could benefit from more detail on the return object structure, though the listed fields are helpful.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing an example parameter object '{ inbound_id: 7, tone: "friendly" }' that clarifies usage, and it mentions the tool's heuristic nature which contextualizes the parameters. This goes beyond the schema's technical descriptions.

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

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

The description clearly states the tool's purpose with specific verbs ('Build a reply-draft skeleton') and resources ('for an inbound email'), distinguishing it from sibling tools like 'reply_to_inbound_email' by focusing on scaffolding rather than sending. It explicitly notes the heuristic nature and that the agent fills in body text.

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

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

The description provides explicit usage guidance: 'When to use: agent received an inbound email and wants to reply' and specifies the workflow: 'Call this to get the draft scaffold, fill in body_placeholder with the actual reply, then call reply_to_inbound_email.' This clearly distinguishes when to use this tool versus its sibling 'reply_to_inbound_email'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the mutation behavior (creates a copy with new ID), the naming convention (suffix ' (copy)'), and the output state (unpublished draft). However, it doesn't mention potential constraints like permissions needed or rate limits.

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

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

The description is efficiently structured with three distinct sentences: the core functionality, usage guidance, and return value example. Each sentence adds essential information with zero wasted words, making it easy for an agent to parse quickly.

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

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

For a mutation tool with no annotations and no output schema, the description provides good coverage of purpose, usage, and behavioral details. It explains what gets created and its state (unpublished draft). The main gap is lack of explicit error conditions or permission requirements, but overall it's quite complete for its complexity.

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

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

Schema description coverage is 100% with the single parameter 'id' well-documented. The description doesn't add additional parameter semantics beyond what the schema provides, but the schema already fully describes the parameter. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the specific action ('Create a copy'), the resource ('existing template'), and key behavioral details (new ID, same body, name suffix). It explicitly distinguishes from sibling tools like 'create_template' by focusing on duplication rather than creation from scratch.

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

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

The description provides explicit guidance on when to use this tool ('agent wants to fork a template before editing so the original remains intact'), which clearly differentiates it from alternatives like 'update_template' or 'create_template'. This gives the agent clear context for tool selection.

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

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

With no annotations provided, the description carries full burden and does well by describing the return format and providing an example. It clearly indicates this is a read operation (listing contacts) and specifies the data structure returned. However, it doesn't mention potential limitations like pagination, rate limits, or authentication requirements, which would be helpful for a tool with no annotations.

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

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

The description is efficiently structured with purpose first, usage guidelines second, return format third, and an example last. Each sentence adds clear value without redundancy. The entire description is front-loaded with the most important information (what the tool does and when to use it).

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

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

For a tool with no annotations and no output schema, the description does an excellent job covering purpose, usage, and return format. The example provides concrete usage context. The main gap is lack of information about behavioral constraints (rate limits, permissions needed, etc.) that would be important for a production tool, but given the rich description of what it returns and how to use it, this is quite complete.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any additional parameter information beyond what's in the schema. The example shows parameter usage but doesn't provide semantic context beyond the schema descriptions. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the specific action ('List contacts who received a broadcast but did NOT click any tracked link in it') with precise resource targeting. It distinguishes itself from sibling tools like 'list_contacts' or 'get_contact_activity' by focusing specifically on non-clickers from broadcasts, making its purpose unambiguous and differentiated.

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

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

The description explicitly states 'When to use: build a follow-up campaign to "people who saw it but didn't act"' and provides specific pairing recommendations with 'create_segment + send_broadcast (or send_email) to re-engage them.' This gives clear context for when to use this tool versus alternatives and suggests practical workflow integration.

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

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

No annotations are provided, so the description carries the full burden. It describes the core behavior (forwarding with cover note) and mentions the return value, but doesn't disclose important behavioral traits like whether this requires specific permissions, if it's idempotent, rate limits, or error conditions. The description adds some value but leaves gaps in 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.

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

The description is appropriately sized with three sentences that each serve distinct purposes: stating the action, providing usage guidance, and showing return format. It's front-loaded with the core functionality. The example could be slightly more concise, but overall there's minimal waste.

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

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

For a mutation tool with no annotations and no output schema, the description provides good purpose and usage context but lacks complete behavioral transparency. It shows the return format through an example, which partially compensates for the missing output schema, but doesn't fully address all aspects a mutation tool should disclose (permissions, side effects, error handling).

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any additional parameter semantics beyond what's in the schema - it mentions 'optional cover note' which corresponds to the 'message' parameter, but this is already covered in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the specific action ('forward an inbound email') and resource ('inbound email'), distinguishing it from sibling tools like 'reply_to_inbound_email' or 'send_email'. It specifies the purpose is to forward with an optional cover note, making the verb+resource combination precise and differentiated.

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

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

The description explicitly provides usage guidance with 'When to use: route a message to a teammate or another address.' This gives clear context for when to select this tool over alternatives like 'reply_to_inbound_email' or general email sending tools, making it easy for an agent to decide when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool returns metadata without the secret, which is crucial behavioral information. It also implies this is a read-only operation (getting metadata) and provides context about what gets returned. However, it doesn't mention potential errors, rate limits, or authentication requirements.

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

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

The description is extremely well-structured and concise. It uses three distinct sections: purpose statement, usage guidelines, and return format example. Each sentence earns its place by providing essential information without redundancy. The information is front-loaded with the core purpose stated first.

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

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

For a single-parameter read operation with no output schema, the description provides excellent context. It explains what the tool does, when to use it, and what it returns. The example helps clarify the return format. However, without annotations or output schema, it could benefit from more detail about error conditions or response structure beyond the brief example.

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

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

Schema description coverage is 100%, so the schema already documents the single 'id' parameter as 'API key ID'. The description doesn't add any additional parameter semantics beyond what's in the schema. The example '{ id: 17 }' illustrates usage but doesn't provide new semantic information about the parameter.

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

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

The description clearly states the tool's purpose: 'Get an API key's metadata' with the specific verb 'Get' and resource 'API key's metadata'. It distinguishes from sibling tools like 'create_api_key' and 'revoke_api_key' by focusing on retrieval rather than creation or deletion. The mention that 'the secret is never returned after creation' further clarifies its read-only nature.

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

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

The description explicitly provides usage guidance: 'When to use: confirm a key's permission, mode or last-used timestamp before revoking.' This gives a clear scenario for when to use this tool (before revoking) and implies an alternative action (revoking via 'revoke_api_key'). It effectively distinguishes this tool from other API key-related operations.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool retrieves details and stats (implying read-only behavior) and describes the return format ('shaped broadcast'), but lacks information on permissions, rate limits, error handling, or whether it's idempotent. It adds some behavioral context but not comprehensively.

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

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

The description is front-loaded with the main purpose, followed by usage guidelines, return details, and an example—all in four concise sentences with no wasted words. Each sentence adds specific value, making it highly efficient.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, usage, returns, and includes an example. However, it could be more thorough by mentioning potential errors or linking to sibling tools for broader context.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value by providing an example ('Example: { id: "br_abc" }'), which clarifies the parameter's usage and format beyond the schema's basic description ('Broadcast ID'), elevating the score.

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

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

The description clearly states the tool's purpose with specific verbs ('Get', 'report on') and resources ('broadcast's details and aggregate delivery stats', 'send results'), distinguishing it from siblings like 'list_broadcasts' (which lists multiple broadcasts) and 'broadcast_performance' (which might focus on analytics rather than details).

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

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

The description explicitly states 'When to use: report on send results... for a specific broadcast', providing clear context for usage. However, it does not specify when not to use it or name alternatives (e.g., 'list_broadcasts' for multiple broadcasts), missing full sibling differentiation.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'full details' and specifies the return shape ('email, names, properties, unsubscribed flag, createdAt'), which adds useful behavioral context. However, it lacks information about error conditions, permissions required, or rate limits, leaving some behavioral aspects unclear.

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

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

The description is efficiently structured with four concise sentences that each serve a distinct purpose: stating the action, providing usage guidelines, detailing returns, and giving an example. There is no wasted language, and key information is front-loaded, making it easy to parse quickly.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and return values adequately. However, without annotations or an output schema, it could benefit from more detail on error handling or permissions, slightly reducing completeness for a read operation.

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

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

The input schema has 100% description coverage, with the single parameter 'id' documented as 'Contact ID'. The description adds minimal value beyond this by mentioning 'by id' in the first sentence and providing an example. Since schema coverage is high, the baseline score of 3 is appropriate, as the description does not significantly enhance parameter understanding.

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

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

The description clearly states the specific action ('Get full details') and resource ('a contact by id'), distinguishing it from sibling tools like 'get_contact_by_email' or 'list_contacts'. It uses precise language that directly communicates the tool's function without ambiguity.

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

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

The description includes explicit 'When to use' guidance ('inspect a specific contact's properties, subscription state, or last activity'), providing clear context for application. However, it does not mention when NOT to use this tool or explicitly name alternatives like 'get_contact_by_email' or 'list_contacts', which prevents a perfect score.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it describes the return structure in detail, explains the email vs. id lookup mechanism, and implies read-only operation through 'Get' and investigation context. However, it doesn't mention rate limits, authentication needs, or error handling, leaving some gaps for a tool with no annotation coverage.

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

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

The description is efficiently structured: first sentence states purpose, second provides usage guidelines, third explains parameter semantics, fourth details return values, and fifth gives an example. Each sentence earns its place with no redundant information, making it easy to scan and understand quickly.

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

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

Given no annotations and no output schema, the description compensates well by fully explaining the tool's behavior, usage, parameters, and return structure. It covers the complexity of a 4-parameter tool with event grouping and lookup mechanisms, making it complete enough for an agent to use effectively without relying on external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic difference between 'email' and 'id' parameters ('email triggers a lookup, id is direct'), which isn't in the schema. It also provides an example with 'limit: 20' to illustrate usage, though it doesn't detail 'since' or default behaviors beyond what the schema already covers.

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

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

The description clearly states the tool's purpose: 'Get a contact's recent email-event timeline grouped by event type' with specific event types listed (sent, delivered, opened, etc.). It distinguishes itself from siblings like 'get_contact' or 'get_engagement_summary' by focusing on detailed event-level activity rather than basic contact info or aggregated summaries.

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

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

The description explicitly provides usage guidance: 'When to use: investigate a specific contact's engagement history before sending — e.g. did they bounce on the last campaign, are they frequently opening, when did they last click.' It also clarifies parameter usage: 'Pass email OR id; email triggers a lookup, id is direct,' which helps differentiate from tools requiring both or other identifiers.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool returns a 404 error if no contact exists (error handling), specifies the return data shape (id, email, names, etc.), and mentions case-insensitive email matching (implied from schema but reinforced). It doesn't cover rate limits or authentication needs, but provides substantial operational context.

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

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

The description is efficiently structured with three focused sentences and an example. The first sentence states the purpose, the second provides usage guidelines and error handling, and the third specifies the return shape. Every sentence adds essential information with zero waste.

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

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

For a single-parameter read operation with no output schema, the description provides complete context: purpose, usage guidelines, error behavior (404), return data structure, and an example. It compensates well for the lack of annotations and output schema, making the tool's operation fully understandable.

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

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

Schema description coverage is 100%, so the schema already fully documents the single 'email' parameter with its type, format, and case-insensitivity. The description adds minimal value beyond the schema (just restating 'email address to look up'), meeting the baseline of 3 for high schema coverage.

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

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

The description clearly states the specific action ('Look up a contact by their email address') and resource ('contact'), distinguishing it from siblings like 'get_contact' (likely by ID) and 'list_contacts' (pagination-based). It explicitly names the key differentiator: email-based lookup.

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

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

The description provides explicit guidance on when to use this tool ('agent has an email address... and wants the full contact record without paginating list_contacts'), when not to use it (returns 404 if no contact exists), and alternatives ('use create_contact to add one'). It also contrasts with 'list_contacts' for pagination scenarios.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by specifying the return format ('Returns: { items: [{ topicId, subscribedAt }] }') and providing an example, which clarifies output structure. However, it doesn't mention potential errors, rate limits, or authentication requirements, leaving some behavioral aspects uncovered.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, return format, and an example—all in four concise sentences. Each sentence adds distinct value without redundancy, making it efficient and easy to parse.

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

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

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is largely complete. It covers purpose, usage, return values, and an example. However, it lacks details on error handling or edge cases (e.g., invalid contact IDs), which could enhance completeness for a read operation.

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

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

The input schema has 100% description coverage (the 'contact_id' parameter is documented as 'Contact ID'), so the baseline score is 3. The description adds minimal value beyond the schema by including an example ('Example: { contact_id: "con_abc" }'), which provides a usage pattern but doesn't significantly enhance parameter understanding.

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

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

The description clearly states the specific action ('List the subscription topics') and resource ('a contact is currently opted in to'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'subscribe_contact_to_topic' or 'unsubscribe_contact_from_topic' by focusing on retrieval rather than modification.

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

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

The description explicitly provides usage guidance with 'When to use: check whether a contact is subscribed to a specific topic before sending.' This gives a concrete scenario for application and implicitly distinguishes it from tools that modify subscriptions, offering clear context for when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool as a read operation ('Get'), specifies the return structure ('shaped domain'), and includes an example. However, it lacks details on error handling, permissions, or rate limits, which would be valuable for a complete behavioral picture.

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

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

The description is efficiently structured with four concise sentences: purpose, usage guidelines, return details, and an example. Each sentence adds clear value without redundancy, and the information is front-loaded with the core purpose, making it easy to parse quickly.

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

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

Given the tool's moderate complexity (single parameter, read operation) and lack of output schema, the description provides good context: it explains what the tool does, when to use it, and the return structure. However, it could be more complete by addressing potential errors or edge cases, slightly reducing the score from a perfect 5.

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

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

The input schema has 100% description coverage, with the 'id' parameter fully documented. The description does not add any additional parameter semantics beyond what the schema provides (e.g., it doesn't explain format constraints or provide examples beyond the basic example). This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the specific action ('Get domain details') and resource ('domain'), listing key components like DNS records and verification status. It distinguishes from siblings like 'list_domains' (which lists multiple) and 'verify_domain' (which performs verification), making the purpose explicit and differentiated.

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

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

The description explicitly provides usage guidance with 'When to use:' clauses, specifying two concrete scenarios: reading DNS records for display and checking verification before sending. This gives clear context for when to invoke this tool versus alternatives like 'list_domains' for listing or 'verify_domain' for verification actions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It effectively describes the return format ('shaped email record + events') and lists specific event types (queued, sent, delivered, opened, clicked, bounced), which helps the agent understand what to expect. However, it doesn't mention potential errors (e.g., invalid ID handling) or performance aspects like rate limits, leaving some behavioral gaps.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines, return details, and an example—all in four concise sentences with zero wasted words. Each sentence adds clear value, making it efficient and well-structured for quick comprehension.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is largely complete: it covers purpose, usage, returns, and provides an example. However, without an output schema, it could benefit from more detail on the return structure (e.g., field descriptions), though the listed event types partially compensate. For a simple read operation, this is strong but not exhaustive.

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

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

The input schema has 100% description coverage (the 'id' parameter is documented as 'Email ID'), so the baseline is 3. The description adds minimal value beyond the schema by reinforcing the parameter's purpose ('for a specific email by id') and providing an example ('{ id: "em_7kf2x9" }'), but it doesn't explain format constraints or semantics not covered in the schema.

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

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

The description clearly states the specific action ('Get full details and event timeline') and resource ('for a specific email by id'), distinguishing it from siblings like 'list_emails' (which lists multiple emails) or 'get_engagement_summary' (which provides aggregated metrics). It precisely defines what the tool does without being vague or tautological.

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

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

The description explicitly states when to use this tool: 'investigate why one email failed/bounced, or confirm delivery for a single send.' This provides clear context for usage and implicitly distinguishes it from tools like 'list_emails' (for bulk overview) or 'get_engagement_summary' (for aggregated analytics).

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

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

No annotations are provided, so the description carries the full burden. It effectively describes the tool's behavior by specifying what data is returned (e.g., segment, lifetime metrics, rates, timestamps, tags) and implies it's a read-only operation through context. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some behavioral aspects uncovered.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, return format, and an example. Each sentence serves a distinct purpose without redundancy, making it efficient and easy to parse for an AI agent.

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

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

Given no annotations and no output schema, the description compensates well by detailing the return structure and providing usage context. It covers the tool's purpose, when to use it, and what to expect, making it largely complete for a read-only tool. A slight deduction as it doesn't address potential edge cases or system behaviors like error responses.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (email and id as alternatives). The description adds minimal value beyond the schema by providing an example with email usage, but doesn't explain parameter semantics like format requirements or mutual exclusivity beyond what's in the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'Get' and the resource 'a single contact's engagement summary', with specific components listed (segment, lifetime counts, open/click rates, etc.). It explicitly distinguishes from sibling 'get_contact_activity' by noting this returns a summary versus raw timeline, providing clear differentiation.

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

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

The description includes a dedicated 'When to use' section with explicit scenarios (e.g., qualifying a contact before sending, checking if someone is a frequent opener, excluding from re-engagement). It names the alternative tool 'get_contact_activity' and explains when to choose this summary tool over that one, offering clear guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a read operation (implied by 'Get'), returns specific data ('shaped inbound email with html/text body and headers'), and provides an example. However, it doesn't mention potential limitations like authentication requirements, rate limits, or error conditions.

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

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

The description is efficiently structured with four sentences that each serve a distinct purpose: stating the tool's function, providing usage context, describing returns, and giving an example. There's no wasted text, and the most critical information (what the tool does) comes first.

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

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

Given the tool's moderate complexity (single parameter read operation), no annotations, and no output schema, the description does well by explaining purpose, usage, returns, and providing an example. However, it could be more complete by mentioning where to get the email ID from (e.g., from list_inbound_emails) or clarifying the return structure further.

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

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

The schema description coverage is 100% (the 'id' parameter is fully described in the schema as 'Inbound email ID'), so the baseline is 3. The description adds minimal value beyond the schema by providing an example ('Example: { id: 7 }'), but doesn't explain parameter semantics like format constraints or where to obtain the ID.

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

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

The description clearly states the tool's purpose with specific verbs ('Get a received inbound email's full headers and body') and distinguishes it from siblings like 'list_inbound_emails' (which lists emails) and 'get_email' (which might retrieve sent emails). It precisely identifies the resource (inbound email) and scope (full headers and body).

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

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

The description explicitly states when to use this tool ('read a specific message before drafting a reply') and names specific alternatives for follow-up actions ('use draft_from_thread or reply_to_inbound_email next'). This provides clear guidance on the tool's role in a workflow context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a read operation ('Get') that returns data, which is adequate for basic transparency. However, it doesn't mention potential authentication requirements, rate limits, error conditions, or whether the operation has side effects, leaving some behavioral aspects unspecified.

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

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

The description is perfectly structured and economical: first sentence states purpose, second provides usage guidelines, third describes return value, fourth gives a concrete example. Every sentence earns its place with zero wasted words, and the most critical information (what the tool does) is front-loaded.

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

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

For a simple read operation with one parameter and no output schema, the description provides good contextual coverage: purpose, usage guidelines, return value description, and an example. The main gap is the lack of output format details (what 'shaped mailbox' means structurally), but given the tool's simplicity and clear sibling differentiation, this is a minor omission.

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

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

The schema description coverage is 100% (the single 'id' parameter is fully documented in the schema), so the baseline score is 3. The description adds minimal value beyond the schema by providing an example format '{ id: 17 }', which reinforces the parameter usage but doesn't provide additional semantic context about valid ID ranges or sources.

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

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

The description clearly states the specific verb ('Get') and resource ('mailbox's metadata'), explicitly listing the metadata fields returned (status, quota, last login). It distinguishes this read operation from sibling tools like 'update_mailbox' and 'delete_mailbox' by focusing on inspection rather than modification.

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

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

The description provides explicit guidance on when to use this tool ('inspect a specific mailbox before updating or deleting'), directly naming the alternative actions (updating/deleting) and establishing a clear prerequisite relationship. This helps the agent understand the tool's role in a workflow context.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ('shaped segment (name, contactCount, createdAt)') and includes an example, which adds useful context. However, it doesn't mention potential errors (e.g., invalid segment ID), rate limits, or authentication requirements, leaving some behavioral aspects unclear.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines, return values, and an example—all in four concise sentences. Each sentence adds value without redundancy, making it efficient and well-structured.

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

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

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, usage, returns, and an example. However, it lacks details on error handling or system constraints, which would be beneficial for full transparency.

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

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

The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'Segment ID.' The description doesn't add parameter details beyond the schema, but it provides an example ('{ id: "seg_abc" }') that reinforces usage. With high schema coverage, the baseline is 3, and the example justifies a 4.

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

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

The description clearly states the tool's purpose with specific verbs ('Get a segment's details and member count') and distinguishes it from siblings like 'list_segments' (which lists segments) and 'create_segment' (which creates segments). It specifies the exact resource being retrieved (segment details and contactCount).

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

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

The description explicitly states when to use this tool: 'confirm a segment's contactCount before broadcasting (to estimate volume).' This provides clear context for usage and distinguishes it from alternatives like 'list_segments' for browsing or 'get_contact' for individual contact details.

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

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

No annotations are provided, so the description carries the full burden. It describes what the tool returns ('shaped template with htmlBody, textBody, variables[], version') and provides an example, which adds useful context. However, it doesn't mention potential errors (e.g., if template doesn't exist), permissions needed, or rate limits, leaving some behavioral aspects unclear.

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

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

The description is efficiently structured with three sentences: purpose, usage guidelines, and return format with example. Each sentence adds distinct value without redundancy, making it easy to parse and understand quickly.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is quite complete. It covers purpose, usage, and return format with an example. However, without annotations or output schema, it could benefit from more detail on error conditions or behavioral constraints to be fully comprehensive.

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

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

Schema description coverage is 100% (the 'id' parameter is fully described in the schema as 'Template ID'), so the baseline is 3. The description doesn't add any additional parameter information beyond what's in the schema, but it does provide an example usage with the parameter, which offers minimal extra context.

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

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

The description clearly states the specific action ('Get a template's full body, subject and variables') and resource ('template'), distinguishing it from siblings like 'list_templates' (which lists templates) and 'create_template' (which creates templates). It provides precise information about what data is retrieved.

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

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

The description explicitly states when to use this tool: 'read the source HTML/text before editing, or extract the variable list to know what to pass in.' This provides clear guidance on appropriate contexts for use, though it doesn't explicitly mention when not to use it or name alternatives.

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

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

No annotations are provided, so the description carries the full burden. It states the tool retrieves details (implying read-only) and mentions the return shape ('shaped webhook'), but lacks details on error conditions, authentication needs, or rate limits. The example clarifies the parameter format, adding some value beyond the basic purpose.

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

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

The description is efficiently structured with four concise sentences: purpose statement, usage guidelines, return information, and an example. Each sentence adds distinct value without redundancy, and the information is front-loaded with the core purpose.

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

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

For a simple read operation with one parameter and no output schema, the description is reasonably complete. It covers purpose, usage, return shape, and provides an example. However, it lacks details on the 'shaped webhook' output structure, which could be helpful given no output schema is provided.

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

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

The input schema has 100% description coverage (the 'id' parameter is documented as 'Webhook ID'), so the baseline is 3. The description adds value by providing an example ('{ id: 17 }') that illustrates the parameter format and expected input structure, enhancing understanding beyond the schema alone.

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

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

The description explicitly states the verb ('Get') and resource ('a webhook's details'), making the purpose specific and clear. It distinguishes from sibling tools like 'list_webhooks' (which lists multiple) and 'create_webhook'/'update_webhook'/'delete_webhook' (which modify rather than retrieve).

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

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

The description includes an explicit 'When to use' section that specifies the context ('inspect the URL, event list, or active state for a specific webhook'), clearly indicating this is for detailed inspection of a single webhook rather than listing all webhooks or performing other operations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by explaining what it does (spam pre-flight), what it returns (score, action, symbols, suggestions), and the meaning of outputs (e.g., score range 0–15+, action types). However, it lacks details on potential side effects, rate limits, or authentication needs, which would be beneficial for a tool with no annotations.

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

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

The description is well-structured and concise, with every sentence adding value. It starts with the core purpose, follows with usage guidelines, explains the return structure, and ends with a practical example. There is no redundant or unnecessary information, making it efficient and easy to parse.

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

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

Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and output details effectively. However, it could improve by mentioning any limitations (e.g., rate limits, error handling) or dependencies, which would enhance completeness for a tool with no structured behavioral annotations.

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

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

The input schema has 100% description coverage, providing clear documentation for all 5 parameters (from, to, subject, html, text). The description does not add any parameter-specific semantics beyond what the schema already states, such as explaining format requirements or constraints. This meets the baseline score of 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose with specific verbs ('Run a Rspamd-backed spam pre-flight') and resources ('on a draft email'), distinguishing it from all sibling tools which focus on contact management, broadcasting, templates, and other email-related operations rather than spam analysis. It explicitly mentions what it returns (score, action, symbols), making its function unambiguous.

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

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

The description provides explicit guidance on when to use this tool ('BEFORE sending agent-generated content') and includes an example that illustrates its application. It distinguishes itself from siblings like 'send_email' or 'preview_email' by focusing on spam detection rather than delivery or rendering, offering clear context for its use case.

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

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

With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses that 'only the prefix is returned, never the full secret' (security constraint) and describes the return format. However, it doesn't mention pagination behavior or rate limits.

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

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

The description is efficiently structured with four concise sentences: purpose statement, security disclosure, usage guidelines, return format, and example. Each sentence adds value without redundancy, and key information is front-loaded.

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

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

For a read-only listing tool with no annotations and no output schema, the description provides good coverage: purpose, security constraint, usage context, return format, and parameter example. It could be more complete by explicitly mentioning pagination behavior or linking to sibling tools like 'revoke_api_key'.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('page' and 'per_page'). The description adds minimal value with 'Example: { per_page: 50 }' which provides a usage hint but no additional semantic meaning beyond what the schema provides.

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

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

The description explicitly states 'List API keys' with the specific verb 'List' and resource 'API keys', clearly indicating a read operation. It distinguishes from sibling tools like 'create_api_key' and 'revoke_api_key' by focusing on listing rather than creation or deletion.

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

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

The description provides explicit usage guidance with 'When to use: audit which keys exist, find a key id to revoke.' This clearly states the intended contexts and distinguishes it from alternatives like 'get_api_key' for retrieving specific key details.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes key behavioral traits: it reveals the return format ('{ items[], meta } — paginated shaped broadcasts with status and counts'), indicates pagination behavior, and provides an example parameter usage. However, it doesn't mention potential rate limits, authentication requirements, or error conditions.

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

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

The description is efficiently structured with four sentences that each serve distinct purposes: stating the core function, providing usage guidelines, describing returns, and giving an example. There's no wasted text, and the most critical information (what the tool does) comes first.

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

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

For a list/read tool with no annotations and no output schema, the description provides substantial context: purpose, usage scenarios, return format with pagination details, and an example. It covers the essential information an agent would need to use this tool effectively. The main gap is the lack of output schema, but the description compensates well by describing the return structure.

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

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

The input schema has 100% description coverage, so the schema already documents both parameters ('page' and 'per_page'). The description provides an example ('Example: { per_page: 20 }') which adds minimal practical context but doesn't significantly enhance understanding beyond what the schema provides. The baseline of 3 is appropriate when schema coverage is complete.

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

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

The description clearly states the tool's purpose as 'List broadcasts' which is a specific verb+resource combination. It distinguishes from sibling tools like 'get_broadcast' by indicating this lists multiple items rather than retrieving a single one. However, it doesn't explicitly differentiate from other list tools like 'list_contacts' or 'list_templates' beyond the resource type.

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

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

The description provides explicit usage guidance with 'When to use: find recent campaigns, audit which broadcasts were sent, or pick one to inspect with get_broadcast.' This gives clear scenarios for when to use this tool and explicitly names an alternative tool ('get_broadcast') for different use cases.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format ('Returns: { items: [property, ...] }') and implies a read-only operation through 'List all', though it doesn't explicitly mention permissions, rate limits, or pagination. It adds useful context beyond basic function but could be more comprehensive for a tool with zero annotation coverage.

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

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

The description is efficiently structured with three sentences: purpose, usage guidelines, and return format. Each sentence adds distinct value without redundancy, and the information is front-loaded with the core function. The example '{}' is minimal but serves its purpose.

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

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

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and return format. However, it could enhance completeness by explicitly stating it's a read-only operation or addressing potential edge cases, which would elevate it to a 5.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on purpose and usage. It earns a high score for not adding unnecessary information, though a perfect 5 would require explicit acknowledgment of the parameterless nature.

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

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

The description clearly states the specific action ('List all custom contact properties') and resource ('defined for this account'), distinguishing it from siblings like 'get_contact_property' or 'create_contact_property'. It precisely communicates the tool's function without ambiguity.

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

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

The description explicitly provides usage guidance with 'When to use: discover which custom fields are available before creating/updating contacts.' This tells the agent exactly when this tool should be employed versus alternatives like 'create_contact_property' or 'update_contact', making it highly actionable.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it describes the return format ('{ items[], meta } — paginated shaped contacts'), indicates pagination behavior, and provides an example of parameter usage. It doesn't mention rate limits or authentication requirements, but covers the essential operational behavior.

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

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

Perfectly structured with four distinct, front-loaded sections: purpose statement, usage guidelines, return format, and example. Each sentence earns its place with zero wasted words. The example is concise yet illustrative of common use cases.

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

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

For a read-only list tool with 100% schema coverage but no output schema, the description provides excellent context: clear purpose, usage guidelines, return format disclosure, and an example. It doesn't explain the structure of items in the return array, but given the schema coverage and the tool's relative simplicity, this is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it mentions 'optional search and segment filtering' which the schema already documents, and provides an example showing search and segment_id usage. No additional syntax or format details are provided beyond what's in the schema descriptions.

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

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

The description clearly states the verb ('List') and resource ('contacts') with specific optional filtering capabilities ('search and segment filtering'). It distinguishes from sibling tools like 'search_contacts' by focusing on browsing/filtering rather than comprehensive searching, and from 'get_contact' by handling multiple contacts.

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

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

Explicit 'When to use' section provides three concrete scenarios: 'browse the contact book, find candidates by email/name fragment, or list members of a segment.' This gives clear context for when this tool is appropriate versus alternatives like 'search_contacts' for more complex searches or 'get_contact' for single-contact retrieval.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'List'), returns structured data with status and tracking flags, and supports pagination via the example. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions.

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

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

The description is highly concise and well-structured: purpose, usage guidelines, return format, and example in four brief lines. Every sentence adds value without redundancy, making it easy to parse and front-loaded with essential information.

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

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

Given the tool's low complexity (list operation with 2 optional parameters) and no output schema, the description is reasonably complete: it covers purpose, usage, return structure, and an example. However, without annotations, it could benefit from mentioning safety (read-only) or pagination defaults for full completeness.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('page' and 'per_page'). The description adds minimal value with an example ('Example: { per_page: 50 }'), which hints at usage but doesn't explain semantics beyond what the schema provides. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'List sending domains.' This is a specific verb ('List') and resource ('sending domains'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_domain' or 'create_domain', which would be needed for a perfect score.

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

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

The description provides explicit usage scenarios: 'choose which domain to send from, or audit which domains are verified.' This gives clear context for when to use the tool. It doesn't specify when NOT to use it or name alternatives (e.g., 'get_domain' for a single domain), preventing a perfect score.

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

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

With no annotations provided, the description carries full burden and does well by disclosing pagination behavior, return format structure, and example usage. It doesn't mention rate limits, authentication requirements, or error conditions, but provides substantial behavioral context beyond basic purpose.

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

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

Perfectly structured with four focused sentences: purpose statement, usage guidelines, return format, and example. Every sentence adds value with zero wasted words, and the most critical information (what it does) comes first.

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

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

For a read-only listing tool with 8 parameters and no output schema, the description provides excellent context: clear purpose, usage scenarios, return format, and example. It could mention default pagination values or error cases, but covers the essential information an agent needs to use this tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema - it mentions 'optional filters' generally and provides one example with 'status' and 'date_from', but doesn't explain parameter interactions or provide additional context not in the schema.

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

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

The description clearly states the tool's purpose with specific verb ('List') and resource ('previously-sent emails'), plus scope ('with optional filters and pagination'). It distinguishes from siblings like 'get_email' (single email) and 'list_contacts' (different resource).

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

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

Explicitly provides 'When to use' guidance with three concrete scenarios: triage delivery, look up recipient history, and filter by status/tag/date. This clearly indicates appropriate contexts without needing to mention alternatives since this is the primary email listing tool among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format ('Returns: { items: [{ filename, contentType, size }] }'), which is crucial behavioral information. However, it doesn't mention potential limitations like pagination, error conditions, or authentication requirements, 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.

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

The description is efficiently structured with four sentences: purpose, usage guidelines, return format, and example. Each sentence serves a distinct purpose with zero wasted words, making it easy to parse and understand quickly.

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

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

For a read-only list tool with no annotations and no output schema, the description does well by specifying the return format and usage context. However, it lacks details on error handling, rate limits, or dependencies (e.g., needing 'get_inbound_email' first to obtain the ID), which would make it more complete for agent invocation.

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

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

Schema description coverage is 100%, so the schema already documents the 'id' parameter as 'Inbound email ID.' The description adds an 'Example: { id: 7 }' which provides concrete syntax, but doesn't explain where to obtain this ID or its valid range. This adds some value beyond the schema but not comprehensive semantics.

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

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

The description clearly states the specific action ('List attachments'), resource ('on an inbound email'), and output format ('filename, size, contentType'). It distinguishes from siblings like 'get_inbound_email' (which retrieves email content) and 'forward_inbound_email' (which forwards emails), 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.

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

The description explicitly states 'When to use: decide whether to download attachments before forwarding or processing,' providing clear context for when this tool should be invoked versus alternatives like 'forward_inbound_email' or 'reply_to_inbound_email' that might involve attachments.

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

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

With no annotations provided, the description carries full burden and does well by disclosing the return format ('{ data: [...], meta } shaped — id, from, subject, receivedAt per message') and providing an example parameter usage. However, it doesn't mention pagination behavior (implied by parameters but not explicitly stated), rate limits, or authentication requirements.

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

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

The description is efficiently structured with purpose statement, usage guidelines, return format, and example in just four sentences. Each sentence adds distinct value with zero wasted words, and the most critical information (purpose) comes first.

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

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

For a read-only list tool with 2 parameters and 100% schema coverage, the description provides good context including usage scenarios and return format. The main gap is the lack of output schema, but the description compensates by describing the return structure. It could be more complete by mentioning pagination behavior or default values.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (page, per_page). The description adds marginal value by providing an example ('Example: { per_page: 20 }') but doesn't explain parameter interactions or provide additional semantic context beyond what the schema provides.

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

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

The description clearly states the specific action ('List inbound emails') and resource ('received by mailboxes on this account'), providing a complete purpose statement. It distinguishes this tool from other list_* tools by specifying 'inbound emails' and from get_inbound_email (singular) by indicating it returns multiple messages.

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

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

The description explicitly provides 'When to use' guidance with three concrete scenarios (triage support inbox, find recent message, filter for messages needing reply). This gives clear context for when this tool is appropriate versus alternatives like get_inbound_email for single messages or other list_* tools for different resources.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the return format ('{ items[], meta }'), indicates pagination ('paginated shaped mailboxes'), and provides an example parameter usage. However, it doesn't mention potential rate limits, authentication requirements, or error conditions.

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

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

The description is perfectly structured and front-loaded: purpose statement first, usage guidelines second, return format third, and example last. Every sentence earns its place with zero wasted words, making it easy for an agent to parse quickly.

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

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

For a read-only list tool with 2 parameters and 100% schema coverage, the description provides excellent context: clear purpose, usage guidelines, return format, and pagination behavior. The only minor gap is the lack of output schema, but the description adequately describes the return structure. It's nearly complete for this tool type.

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

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

Schema description coverage is 100%, so the schema already documents both parameters completely. The description provides an example parameter usage ('Example: { per_page: 50 }') which adds minimal value beyond what the schema provides. This meets the baseline expectation when schema coverage is high.

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

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

The description clearly states the specific action ('List mailboxes') and scope ('across all domains'), distinguishing it from sibling tools like 'get_mailbox' (singular) and 'list_domains'. It provides a precise verb+resource combination that immediately communicates the tool's function without ambiguity.

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

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

The description explicitly includes 'When to use' guidance with two concrete use cases: 'see which inboxes exist' and 'find a mailbox id by email address'. This provides clear context for when an agent should select this tool over alternatives like 'search_contacts' or 'get_mailbox'.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ('Returns: { segments: [...] } — array of shaped segments with contactCount') and includes an example with pagination, which adds useful behavioral context. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some gaps for a mutation-free tool.

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

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

The description is well-structured and concise, with four sentences that each serve a distinct purpose: stating the tool's function, providing usage guidelines, specifying the return format, and giving an example. There is no wasted text, and information is front-loaded effectively.

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

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

Given the tool's simplicity (2 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, return format, and an example. However, without annotations or an output schema, it could benefit from more detail on error handling or pagination behavior, though not strictly required for a list operation.

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

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

The input schema has 100% description coverage, with clear documentation for 'page' and 'per_page' parameters. The description adds an example ('Example: { per_page: 50 }') that illustrates usage but doesn't provide additional semantic meaning beyond what the schema already states. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'List contact segments.' This is a specific verb ('List') and resource ('contact segments'), making the function immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_contacts' or 'get_segment' beyond the resource name, which keeps it from a perfect score.

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

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

The description provides explicit usage guidelines: 'When to use: pick a segment id for create_broadcast or list_contacts(segment_id=…).' This clearly states the intended context and alternatives, helping an agent understand when to invoke this tool versus others for related tasks.

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

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

With no annotations provided, the description carries full burden. It discloses the return structure ('Returns: { items: [topic, ...] } shaped') which is valuable behavioral information not available elsewhere. However, it doesn't mention potential limitations like pagination, rate limits, or authentication requirements, leaving some behavioral aspects uncovered.

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

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

The description is perfectly structured and front-loaded: purpose statement first, usage guidelines second, return format third, and example last. Every sentence earns its place with zero wasted words, making it highly efficient for an AI agent to parse.

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

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

For a zero-parameter read operation with no output schema, the description provides excellent context: clear purpose, usage guidelines, and return format. The only minor gap is the lack of output schema, but the description compensates well by specifying the return structure. It's nearly complete for this tool's complexity level.

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

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

The tool has 0 parameters with 100% schema description coverage, so the baseline would be 3. However, the description adds value by clarifying that this lists 'all subscription topics defined for this account,' providing context about scope that isn't captured in the empty parameter schema. This elevates the score above baseline.

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

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

The description clearly states the specific action ('List all subscription topics') and resource ('defined for this account'), distinguishing it from sibling tools like 'create_subscription_topic' and 'delete_subscription_topic'. It provides a precise verb+resource combination that leaves no ambiguity about its function.

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

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

The description explicitly provides usage guidance with 'When to use: pick a topic_id for a broadcast, or audit which preferences exist.' This gives clear scenarios for when to invoke this tool versus alternatives, directly addressing the agent's decision-making needs.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a read-only list operation (implied by 'List'), returns paginated data with specific structure ('{ items[], meta }'), and includes metadata fields ('reason and createdAt'). It also provides a concrete example of parameter usage. However, it doesn't mention rate limits, authentication requirements, or error conditions.

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

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

The description is efficiently structured with four sentences that each serve distinct purposes: purpose statement, usage guidelines, return format, and parameter example. No wasted words, and the most critical information (what the tool does) comes first.

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

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

For a read-only list tool with 2 parameters and no output schema, the description provides good coverage: purpose, usage scenarios, return format with field details, and a parameter example. The main gap is lack of output schema, but the description compensates reasonably well by describing the return structure. It could benefit from mentioning pagination behavior more explicitly.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (page, per_page). The description adds minimal value beyond the schema by providing an example ('Example: { per_page: 100 }'), but doesn't explain parameter interactions, default values, or constraints beyond what's in the schema descriptions.

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

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

The description clearly states the specific action ('List suppressed email addresses') and resource ('email addresses'), with explicit scope ('will not receive any emails'). It distinguishes from sibling tools like 'add_suppression' and 'remove_suppression' by focusing on listing rather than modifying.

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

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

The description provides clear usage context ('audit which addresses are blocked, or paginate to find a specific entry'), giving practical scenarios for when to use this tool. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns paginated results ('Returns: { items[], meta } — paginated shaped templates'), which is valuable behavioral context not inferable from the input schema alone. It doesn't mention rate limits or authentication needs, but for a read-only list operation, the pagination disclosure is sufficient for a high score.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines, return format, and an example—all in four concise sentences. Each sentence adds value without redundancy, making it efficiently structured.

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

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

Given the tool's low complexity (a simple list operation with two optional parameters) and no output schema, the description is complete: it explains the purpose, usage, return format (including pagination), and provides an example. This covers all necessary aspects for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('page' and 'per_page'). The description adds an example ('Example: { per_page: 50 }'), which provides a usage hint but doesn't add significant semantic meaning beyond what the schema provides. This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the verb ('List') and resource ('email templates'), making the purpose specific. It distinguishes from siblings like 'get_template' (which retrieves a single template) and 'create_template' (which creates new templates), establishing its role as a listing operation.

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

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

The description explicitly provides usage scenarios: 'pick a template id for send_email or render_template, or audit which templates exist.' This gives clear context for when to use this tool versus alternatives like 'get_template' for detailed info on a specific template.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ('{ webhooks: [...] } — array of shaped webhooks'), which is valuable behavioral information not in the input schema. However, it lacks details on pagination behavior (e.g., default values, error handling) and whether the operation is read-only or has side effects, leaving some gaps for a tool with no annotations.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines, return format, and an example—all in four concise sentences with zero waste. Each sentence earns its place by adding distinct value (purpose, context, output, usage hint), making it highly efficient and well-structured.

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

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

Given the tool's low complexity (list operation with 2 optional parameters), 100% schema coverage, and no output schema, the description is mostly complete. It covers purpose, usage, and return format, but lacks full behavioral transparency (e.g., pagination defaults, error cases). With no annotations, it could benefit from more detail on safety and operational limits, but it's adequate for a simple list tool.

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

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

The input schema has 100% description coverage (both parameters are documented), so the baseline is 3. The description adds minimal value beyond the schema by providing an example ('Example: { per_page: 50 }'), which hints at usage but does not elaborate on parameter interactions or constraints. It does not compensate for any schema gaps, as there are none.

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

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

The description clearly states the verb ('List') and resource ('configured webhook endpoints'), making the purpose specific and unambiguous. It distinguishes itself from sibling tools like 'get_webhook' (singular) and 'create_webhook'/'delete_webhook'/'update_webhook' (mutations), establishing a clear scope for listing multiple endpoints.

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

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

The description explicitly provides a 'When to use' clause ('audit which integrations are receiving events'), giving clear context for when this tool is appropriate. It implicitly distinguishes from sibling tools by focusing on listing rather than creating, getting, updating, or deleting webhooks, though it does not explicitly name alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates this is a non-destructive preview operation ('WITHOUT sending it'), describes the multi-function nature (render, lint, measure), and specifies the return structure. However, it doesn't mention rate limits, authentication requirements, or error conditions.

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

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

The description is efficiently structured with zero waste. The first sentence states the core functionality, the second provides usage context, the third explains the combined operations, and the final sections detail returns and provide an example. Every sentence earns its place.

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

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

For a 7-parameter tool with no annotations and no output schema, the description does well by explaining the multi-function nature, providing usage context, and detailing the return structure. However, it doesn't cover error cases, rate limits, or authentication requirements that would be helpful for a mutation-like tool (even though it doesn't send).

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it mentions template_id triggers template rendering and provides an example with variables, but doesn't significantly enhance understanding of parameter interactions or constraints beyond what's in the schema.

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

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

The description clearly states the tool's purpose with specific verbs ('Render + lint + measure an email') and distinguishes it from siblings by explicitly mentioning it's for previewing 'BEFORE send_email'. It also differentiates from render_template by noting it combines multiple functions in one round-trip.

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

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

The description provides explicit guidance on when to use this tool ('BEFORE send_email when the body was generated by the agent') and mentions an alternative (send_email). It also clarifies the relationship with render_template, indicating this tool can handle template rendering as part of its functionality.

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

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

No annotations are provided, so the description carries full burden. It states the action (publishing) and return value ('shaped template with published=true'), which implies a mutation. However, it doesn't mention permissions needed, whether the operation is reversible (though 'unpublish_template' exists), or any side effects like notifications. The description adds basic behavioral context but lacks depth for a mutation tool.

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

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

Front-loaded with purpose, followed by usage guidelines, return value, and an example. Every sentence adds value with zero waste, and the structure is logical and easy to parse.

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

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

Given 1 parameter with 100% schema coverage and no output schema, the description is reasonably complete: it explains purpose, usage, and return value. However, as a mutation tool with no annotations, it could better address permissions or reversibility. The sibling 'unpublish_template' hints at reversibility, but this isn't explicitly stated.

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

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

Schema description coverage is 100%, so the schema already documents the single 'id' parameter. The description adds minimal param semantics through the example '{ id: "tpl_abc" }', which clarifies the expected format. With 0 parameters, baseline would be 4, but here the example provides slight extra value beyond the schema.

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

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

The description clearly states the action ('Mark a template as published'), the resource ('template'), and the purpose ('so it can be referenced by send_email'). It distinguishes from siblings like 'create_template' (creation), 'update_template' (editing), and 'unpublish_template' (opposite action).

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

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

Explicitly provides when-to-use guidance: 'after creating or editing a template you have validated and want available for sending.' This clearly indicates the prerequisite state and intent, differentiating from alternatives like 'create_template' (initial creation) or 'update_template' (editing without publishing).

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