Nevent MCP

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds contextual workflow details but does not disclose additional behavioral traits like response format, pagination, or rate limits. It is adequate but not rich, consistent with the bar set by 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 two sentences with no redundancy. The core purpose is front-loaded, and the workflow guidance is delivered in a compact, directive sentence. Every word 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 zero-parameter, read-only discovery tool, the description is complete: it states the purpose, provides the correct invocation order relative to two key sibling tools, and the annotation title reinforces the intent. Nothing needed to call it correctly is missing.

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 zero parameters, so the baseline is 4. The description naturally has no parameter details to provide, and the schema fully covers the (empty) parameter set. No compensation is needed.

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

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

The description states a specific verb ('Discover'), a clear resource ('available analytics tables and their summary metadata'), and distinguishes itself from siblings by explicitly naming the workflow sequence with nevent_analytics_query and nevent_analytics_table_schema. This makes it immediately clear what the tool does and how it differs from related 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: 'Call this before nevent_analytics_query, then use nevent_analytics_table_schema...' This tells the agent exactly when to use this tool and what to use as the next step, effectively routing to the correct sibling tools without ambiguity.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description ('Get distinct values') is fully consistent with those. The description adds modest behavioral context — that outputs serve as valid filter inputs — but does not disclose return format, result limits, or how multiple fields in the filters array interact.

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?

Two sentences with zero filler. The first sentence front-loads the verb and resource, and the second adds the use case. Every word 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 simple read-only tool with fully documented parameters, the description covers the essential context: what it returns (distinct values) and when to use it (before querying). There is no output schema, so a brief note on the response shape would strengthen it, but nothing critical is missing for correct 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 both collection and filters are already documented in the schema, including nested field/value/operator details. The description text adds no parameter-level meaning beyond what the schema provides, so the high-coverage baseline of 3 applies.

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 uses a specific verb+resource ('Get distinct values available for a field in an analytics table') and adds a clear use case ('building valid filter values before querying'). It is not a tautology and reads distinctly from nevent_analytics_query and nevent_analytics_table_schema, though it does not explicitly disambiguate against nevent_dimension_values, which could plausibly overlap.

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 phrase 'before querying' supplies an implied invocation context, telling the agent this is a pre-query preparation step. However, no alternatives are named and no when-not-to-use conditions are given, despite close siblings like nevent_analytics_table_schema and nevent_dimension_values existing.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds genuine behavioral constraints beyond that: the API will fail or misbehave if field names are guessed, boolean fields reject 'eq' with string values, and enum filters must use documented valid values. It does not mention error behavior or result limits, but the schema independently documents limit and dryRun.

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 one-sentence purpose statement is front-loaded and the mandatory rules are numbered and scannable. Every clause earns its place — the rules target the three highest-risk failure modes. Slightly long given the schema already documents operators and collections, but the redundancy is justified because these are stated as prohibitions rather than descriptions.

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 16-parameter, nested-object tool with 100% schema coverage, the description's job is to highlight what the schema cannot: the discovery workflow, operator traps, and valid enum domains. It does that well, covering the principal blind spots for an agent. With no output schema, return-shape expectations are left unspecified, and newer features like CTEs, comparePeriods, and groupBy are not mentioned in prose — minor gaps since the schema documents them.

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 coverage is 100%, so the schema carries the full burden of documenting all 16 parameters — baseline 3. The description adds real value on top by giving collection-specific valid values for common filter fields (purchases.state = SUCCEEDED|COMPLETE|PENDING|FAILED, campaigns.status = EXECUTED|DRAFT|PAUSED|STOPPED) and by constraining how the 'operator' parameter must be used for booleans, which the schema's 'value' description does not fully convey.

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 opens with a specific verb+resource: 'Query event marketing analytics', then enumerates the capability surface (dimensions, metrics, time ranges, filters) and the data domains (campaigns, purchases, users). This clearly differentiates it from the many sibling lookups like nevent_get_campaign_metrics or nevent_list_campaigns, which are narrower retrieval tools rather than a general analytics query engine.

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 'MANDATORY RULES' block is exactly the guidance an agent needs: it explicitly names the sibling nevent_analytics_table_schema as an unconditional prerequisite ('ALWAYS call ... BEFORE querying'), and gives the precise boolean operator contract (is_true/is_false, never eq with strings) and concrete enum value sets for purchases.state and campaigns.status. This leaves no inference about the most failure-prone aspects of using the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safety profile. The description adds that the tool returns the 'full column schema' with names/types/descriptions, which is useful output context, but it does not disclose additional behavioral details such as errors or availability.

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?

One sentence, no filler, and the core action is front-loaded. Every word serves to clarify what the tool 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?

The tool is low-complexity: one required parameter, fully documented schema, and annotations covering read-only/non-destructive behavior. The description also states what the response contains, so nothing an agent needs to invoke it is missing.

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% and the single 'table' parameter is already described with an example. The description adds nothing beyond the schema for parametr semantics, so baseline 3 applies.

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 ('Get') and the resource ('full column schema for a specific analytics table'), and enumerates the returned content (column names, types, descriptions). It is unambiguous, though it does not explicitly distinguish itself from sibling 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 implies when to use the tool - when the agent needs the schema of a named analytics table - but it gives no explicit when-not criteria or alternatives. Among the many sibling tools, there is no guidance about how this tool relates to them.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: it executes 13 parallel queries in one call and returns a specified list of metrics, which helps the agent understand cost, scope, and output shape. It does not cover response structure or rate limits, but the annotations cover the safety profile.

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

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

The description is two concise sentences, front-loaded with the action and scope. The performance note (13 parallel queries) and the ID prerequisite are efficient additions without fluff. 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?

Given no output schema, the description lists the primary returned metrics and notes there are additional 'other key performance metrics.' It covers the essential return categories, the single-campaign scope, and the ID source. The vague 'other key performance metrics' leaves some ambiguity, but for an analytics report tool this is reasonably 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%: campaignId and timeRange are already documented, including the default behavior of timeRange. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 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 a specific verb ('Generate') and resource ('a comprehensive analytics report for a single campaign'), and enumerates the main metrics returned. It does not explicitly distinguish itself from similar report/insights siblings like nevent_get_campaign_metrics or nevent_get_campaign_insights, so it falls short of a 5.

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

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

The description provides clear context: use it for a single campaign report and use nevent_list_campaigns to obtain valid campaign IDs. It does not state when not to use it or name alternatives, but the single-campaign scope and prerequisite are clear.

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?

Annotations already signal readOnlyHint=false and destructiveHint=false, correctly indicating a non-destructive write. The description adds useful behavioral context beyond those annotations by disclosing the return shape ('Returns the new cloned template (id, name with '(Copy)' suffix, format, tags)') and the naming side effect. This is valuable context for a tool with no output schema, and it contradicts no annotation.

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?

Four short sentences, each earning its place: purpose, prior workflow step, return value, and follow-up workflow. The core purpose is front-loaded and there is zero redundancy or filler.

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 one-parameter tool with no output schema, this is complete: the purpose, prerequisite step, return shape, and follow-up steps are all disclosed. An agent knows what to supply (template_id), what it gets back, and what to do next, with annotations covering the write/non-destructive safety 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?

Schema description coverage is 100%; the schema already fully documents template_id, including how to discover valid IDs via nevent_list_templates and the resulting new ID and '(Copy)' suffix. The description reinforces this but adds no parameter meaning beyond what the schema provides, so the baseline 3 applies.

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 uses a specific verb-resource pair ('Clone an existing email template') and states the intent ('create a duplicate as a starting point for a new campaign'). It distinguishes itself from the closest sibling nevent_create_template by framing this as duplication of an existing resource 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 gives explicit sequencing context: 'Use after nevent_list_templates to pick a template to duplicate' and 'typically follow with nevent_rename_template and nevent_update_template to customize the clone.' This clearly situates the tool in a workflow, though it does not explicitly state when not to use it or name a direct alternative such as create_template for blank templates.

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?

The description goes well beyond annotations by explaining that this is a WRITE operation requiring STANDARD or FULL mode, that READ_ONLY mode returns operation_not_permitted without an API call, and that parentShortCode appears in both path and body and must match. These are meaningful behavioral disclosures beyond the readOnlyHint/destructiveHint flags.

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 dense but every sentence earns its place: purpose, prerequisite, required params, return shape, follow-up tool, mode restrictions, and validation note. It is front-loaded with the core purpose and contains no filler.

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 write tool with no output schema, the description is unusually complete: it names inputs, sources for those inputs, expected return fields, a required prior step, a recommended next step, execution-mode constraints, and a server-side validation rule. An agent has enough context to invoke it correctly and interpret results.

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 coverage is 100%, so the baseline is 3, but the description adds practical parameter context: parentShortCode should come from nevent_list_short_urls, userIds generate per-user tracking links, and the path/body matching constraint is a useful gotcha not present in the schema. This raises it slightly 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 opens with a specific verb and resource: 'Generate per-user short URL variants for an existing parent short URL.' It clearly differentiates this from nevent_create_short_url by emphasizing the parent URL must already exist, and from read-only siblings like nevent_list_short_urls and nevent_get_short_url_metrics.

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?

Usage guidance is explicit and actionable: create the parent first with nevent_create_short_url, obtain parentShortCode from nevent_list_short_urls, and follow up with nevent_get_short_url_campaign_metrics. It also states mode requirements for this write operation and the immediate error behavior in READ_ONLY mode.

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?

It clearly discloses a key behavioral trait: 'The campaign is always created in DRAFT status — no messages are sent.' This goes beyond the readOnlyHint/destructiveHint annotations and directly addresses the main risk of a campaign-creation tool. It also adds a useful safety instruction to confirm the segment audience count before scheduling.

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 organized: overview, prerequisites, status, next step, required fields, optional fields, and safety guardrail. It is dense and front-loaded, though the optional-field list partly repeats schema information and adds to the overall length. For a 16-parameter tool this is acceptable.

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?

Combined with the input schema's full property coverage, the description covers the core purpose, draft semantics, channel-specific requirements, and the follow-up scheduling step. It does not mention the return value, and it does not explicitly address required fields for ALL_CHANNELS/OMNICHANNEL, but the schema enum and the deprecation notes cover much of that 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 coverage is 100%, so the baseline is 3. The description adds channel-conditional required-field guidance and explains when reply_to is useful, but it also introduces inconsistencies: it says 'segment_id' while the schema property is segment_ids, treats optional template_id/segment_ids as prerequisites, omits email_body from the optional-field list, and its message-required rule for PUSH/multi-channel is not reflected in the schema's property 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 opens with a specific verb and object — 'Create a new campaign draft' — and enumerates the supported channel types. It clearly distinguishes itself from sibling tools by emphasizing that the result is only a DRAFT and that no messages are sent, which separates it from nevent_schedule_campaign.

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 an explicit workflow: fetch segment and template IDs first, create the draft, then call nevent_schedule_campaign, and confirm audience count before scheduling. However, it frames segment_ids and template_id as prerequisites even though the schema marks them optional, which slightly overstates when this tool must be used.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds valuable behavioral context beyond annotations: the operation persists state ('Create and persist'), mandates a prerequisite dependency, and discloses a known API limitation about mixing criterion types. No contradiction with annotations. Minor gap: it doesn't describe the response/return shape, though no output schema exists.

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 and front-loaded: purpose sentence first, then labeled sections (PREREQUISITE, MANDATORY RULES, KNOWN LIMITATION) and a closing workflow. Every section earns its place, though the description runs long and partially repeats schema content (entity operator arrays, modifier omission, time_range constraint) that the input schema already states.

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 this complex — nested DSL objects, 3 params, no output schema — the description covers prerequisites, mandatory call-format rules, a known API limitation, and the complete surrounding workflow. The only notable gap is the absence of any statement about what the call returns (e.g., segment ID), which matters more because no output schema exists to fill that void.

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 coverage is 100% and the schema itself is extremely detailed — it already documents entity operators accepting arrays, modifiers being omitted by default, time_range.value > 0, and value typing rules. The description condenses these same rules into mandatory directives, which is useful reinforcement, but it mostly duplicates the schema. The genuinely new semantic is the attendance-vs-spending mixing limitation and the 'omit id, timeframe, type' rule, which adds some value but doesn't dramatically exceed the schema's 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 states a specific verb+resource+source: 'Create and persist a new audience segment from a filter definition.' It distinguishes itself from siblings by naming the surrounding workflow — nevent_segmentation_criteria as prerequisite, nevent_segment_preview and nevent_create_campaign as follow-ups — so an agent can tell it apart from update/list/get segment tools without opening their schemas.

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 the prerequisite (call nevent_segmentation_criteria first), gives when-not-to-use guidance (omit modifiers unless the user explicitly requests frequency/recency filtering), and names the post-creation sequence (preview, then create_campaign). It also provides an exclusion rule (don't mix attendance and spending criteria in the same stanza). Nothing is left to inference.

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?

The description adds significant behavioral detail beyond the annotations: persistence is immediate, the short code becomes active upon return, the return DTO shape is listed, and mode-dependent error behavior is disclosed. Annotations only state readOnlyHint=false and destructiveHint=false; the description gives the operational context an agent needs.

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

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

Every sentence earns its place: purpose, persistence behavior, required fields, return structure, sibling linkage, and operational mode. The information is front-loaded and compact with no redundant or filler content.

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 there is no output schema, the description correctly enumerates the returned DTO fields. It covers input requirements, side effects, mode restrictions, and a natural downstream usage, leaving no critical gap for an agent deciding whether and how to invoke this tool.

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

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

Schema coverage is 100%, so the schema already documents each parameter with examples, formats, and constraints. The description adds only that longUrl is minimally required and other fields are optional—both already reflected in the schema's required array—so it provides marginal value beyond the structured data.

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

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

The description states a specific verb and resource: 'Create a new short URL that redirects to the specified destination.' It clearly distinguishes this creation tool from the many listing, retrieval, and update siblings such as nevent_update_short_url and nevent_list_short_urls.

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?

It specifies the minimum required input (longUrl), notes that all other fields are optional, and explicitly conditions usage on operation mode: WRITE requires STANDARD or FULL, and READ_ONLY fails fast without an API call. It also points users to nevent_create_bulk_user_short_urls as the downstream tool for per-user variants, providing clear alternatives and sequencing.

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?

Annotations already convey a non-read-only, non-destructive mutation. The description adds that the template is saved and reusable across campaigns, which is useful but does not disclose additional behavioral traits such as idempotency, uniqueness constraints, or required permissions.

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?

Three tight sentences: core action first, a targeted format preference second, and a follow-up workflow step third. Every sentence earns its place with no redundant content.

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?

Since there is no output schema, the description usefully explains that a template id is returned and how to use it in nevent_create_campaign. The relationship between format and body fields is left to the schema, but the schema covers it. The description is adequate for correct 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 all parameters. The description adds meaningful guidance beyond the schema by recommending format='MJML' for responsive email, which helps the agent choose the correct enum value and corresponding body field.

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

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

The description states a specific verb and resource: 'Create and persist a new email template.' It identifies the content options (MJML or raw HTML) and distinguishes creation from related sibling tools like nevent_update_template and nevent_clone_template.

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?

Clear context is given: use this tool to create a reusable template, prefer MJML for responsive email, and then call nevent_create_campaign with the returned template id. However, it does not explicitly state when to use alternatives like update, clone, or preview.

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?

Annotations already mark the tool as destructive (destructiveHint=true), and the description adds meaningful context beyond that: the operation is irreversible, and email template HTML referencing deleted URLs will show broken images. It also specifies permission requirements, which helps the agent anticipate errors.

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 compact and well-structured. It opens with the core action and irreversibility, then adds the URL-source guidance, the broken-image consequence, and finally the access requirements. Every sentence adds relevant information without padding.

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 single-parameter destructive tool, the description covers the key operational context: how to obtain valid inputs, irreversibility, side effects, and required permissions. There is no output schema, but the description does not need to explain return values in depth for a delete operation; a small gap is the lack of any mention of success or failure response behavior.

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 URLs array, minimum item count, and example. The description repeats the source guidance (src/destinationUrl) but does not add significant new parameter-level meaning beyond what the schema already 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 uses a specific verb and resource: 'permanently delete one or more images from the Nevent media library.' It clearly distinguishes the operation from sibling tools by specifying the target resource and even tells the agent where to source valid URLs (nevent_list_images or nevent_upload_image).

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 gives clear prerequisites for use: URLs must come from nevent_list_images or nevent_upload_image, and FULL operation mode with ADMIN, SUPERADMIN, or OWNER role is required. It does not explicitly compare against alternative tools, but for a deletion operation the context and preconditions are well stated.

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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), lowering the burden on the description. The description adds the autocomplete/search-filtering behavior, but does not disclose return format, result limits, or matching semantics. For a simple read-only lookup these are minor gaps given 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?

Two sentences with the core function front-loaded in the first sentence. The second sentence is slightly redundant ('discovering valid values' restates 'autocomplete values') but earns its place by adding the segment-building context. No wasted words overall.

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 two-parameter, read-only tool with fully described schema properties and safety annotations, the description adequately covers purpose and usage context. The main omission is the return format, but with no output schema and self-explanatory autocomplete semantics, this is a modest 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 coverage is 100%: both parameters are well documented, with criterion_id referencing its source ('from nevent_segmentation_criteria') and giving concrete examples like 'country' and 'event_attended'. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies.

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 first sentence, 'Autocomplete values for a segmentation criterion,' names a specific verb and resource clearly. The second sentence anchors it to segment definition building, which implicitly separates it from analytics-filter siblings like nevent_analytics_filter_values, though that differentiation is not explicit.

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?

'Useful for discovering valid values when building segment definitions' gives an implied usage context but does not state when to prefer this tool over similar discovery tools such as nevent_analytics_filter_values, nor does it mention exclusions. The guidance is present but left to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by specifying exactly what data the retrieval returns (email subject, body HTML, sending profile, delivery/engagement metrics, tracked links with click counts), and clarifies the intended call sequence relative to other tools. This goes beyond the annotations without contradicting them.

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

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

The description is efficiently structured: the first clause states the core action and scope, the middle enumerates return contents, and the final sentence frames the workflow. Every sentence earns its place with no redundancy or filler.

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?

With only one parameter and a read-only annotation, the description is complete enough: it enumerates the return content in detail, signals the safe read nature, and places the tool in a clear workflow sequence. Since there is no output schema, the explicit list of returned data compensates well.

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 campaign_id and tells agents to use nevent_list_campaigns to discover valid IDs. The tool description reinforces this same guidance but does not add any new parameter-level semantics, such as format, constraints, or examples. Baseline 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 uses a specific verb ('Retrieve') with a clear resource ('complete record of a campaign') and enumerates the contained fields: subject, body HTML, sending profile, metrics, and tracked links. It also distinguishes itself from siblings by positioning it as the drill-down after nevent_list_campaigns and differentiates next-step tools like nevent_get_campaign_insights and nevent_campaign_report.

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 gives explicit workflow guidance: 'Call this after nevent_list_campaigns to drill into a specific campaign.' It also names the next steps (nevent_get_campaign_insights for AI recommendations, nevent_campaign_report for full analytics query), effectively telling an agent when to use this tool versus the 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?

Annotations already mark the tool as read-only and non-destructive; the description adds behavioral context beyond that by noting the analysis is pre-computed, AI-generated, and narrative rather than raw numbers. It does not discuss staleness or latency, but the added context is meaningful.

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?

Three sentences, each earning its place: first states what the tool returns, second gives the invocation trigger, third clarifies the relationship to the sibling raw-metrics tool. No filler or repetition.

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 one-parameter read-only tool with annotations covering safety and no output schema, the description sufficiently explains the return value and invocation context. The workflow anchor to nevent_get_campaign resolves likely sibling confusion, including with nevent_get_paid_campaign_insights.

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 coverage is 100% and the campaign_id parameter is already described in the schema, including a pointer to nevent_list_campaigns for discovery. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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 uses a specific verb and resource: 'Get pre-computed AI analysis for a specific campaign' and enumerates the output (performance summary, detected anomalies, recommendations). It distinguishes itself from nevent_get_campaign by saying it complements raw metrics with narrative insights.

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?

It explicitly says to call this after nevent_get_campaign, gives concrete user-phrase triggers ('how did this campaign perform?' or 'what could be improved?'), and frames it as a complement to raw metrics rather than a replacement. This is clear when-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by revealing that this tool reads directly from nev-api, is the operational source of truth, and that the alternative report lags behind due to the analytics pipeline. It also discloses the kind of counters and rates an agent can expect.

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 and metric list. Each sentence earns its place: metric enumeration, source-of-truth positioning, alternative routing, and follow-up guidance. There is no filler.

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-only tool, the description is remarkably complete. It lists all returned metrics (compensating for the missing output schema), explains data freshness and credibility relative to a sibling, provides usage and alternative conditions, and suggests a follow-up tool. An agent has everything needed to invoke this tool correctly and interpret results.

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 coverage is 100% for the single campaign_id parameter, and the schema description already explains where to get it (nevent_list_campaigns or nevent_create_campaign). The description repeats the nevent_list_campaigns source but adds no new parameter meaning 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 states a specific verb ('Get') and resource ('delivery and engagement counters nev-api holds for one campaign'), and enumerates the exact metrics returned. It clearly differentiates itself from the sibling nevent_campaign_report by positioning itself as the operational source of truth.

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 gives explicit when-to-use guidance: use it right after a send and prefer it over nevent_campaign_report when the two disagree. It also specifies when to use the alternative (comparing many campaigns, slicing by dimension, joining with analytics) and tells the agent how to obtain campaign_id from nevent_list_campaigns.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description goes well beyond this by disclosing transient behavior (null imageUrl/videoUrl means the mirror job hasn't run — retry in ~5 minutes), time sensitivity (S3 URL TTL ~1 hour), structural variance (DCA variants when hasDca: true), and error semantics (404 enrollment caveat). No contradiction with 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?

Four dense sentences, each earning its place: scope of return, prerequisite sequencing, null/retry behavior, DCA special case, and 404 error routing. The core purpose is front-loaded in the first sentence, and there is zero filler or repetition of annotation data.

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?

With no output schema, the description carries the burden of describing the response — and it does, naming all key fields (copy components, click URL, UTM params, imageUrl/videoUrl, hasDca/dca). It also covers error semantics (404), transient states (null URLs), and prerequisites. For a 2-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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 adequately, warranting the baseline of 3. The description restates the adId sourcing guidance ('Use after nevent_list_paid_ads') that already appears in the schema's adId description, reinforcing but not adding substantial new parameter-level meaning.

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

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

The description states a specific verb and resource: 'Get the creative content of a specific ad' and enumerates the exact fields returned (copy, click URL, UTM params, pre-signed S3 URLs). This clearly distinguishes it from sibling tools like nevent_list_paid_ads (listing) and nevent_get_paid_ad_group_insights (ad groups/insights).

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?

Gives explicit sequencing guidance: 'Use after nevent_list_paid_ads to get a valid adId.' It also names a concrete alternative for a failure mode: 'A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.' Both the prerequisite and the fallback are explicit, not left to inference.

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?

Annotations already signal readOnlyHint=true and destructiveHint=false, so the description's value is in additional behavioral context: it explains the ratioVsMean semantics, the direction of 'better/worse' for cost metrics versus CTR, and the possible 404 pilot-enrollment condition. This goes beyond the structured data, though it stops short of fully describing the response format.

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 dense but purposeful: it front-loads the core comparison purpose, then explains metric interpretation, follows with a dependency note, and closes with an error-handling hint. Every sentence earns its place, and the structure guides an agent from selection to invocation to troubleshooting.

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 there is no output schema, the description compensates well by naming the returned metrics (costPerResult, CPM, frequency, CTR), defining ratioVsMean, and explaining how to interpret ratios. It also covers the key prerequisite and a common failure mode, making it largely sufficient for correct invocation and result interpretation.

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 repeats the adGroupId sourcing guidance already present in the schema but does not add new parameter-level detail about from/to defaults or provider values, which 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 opens with a specific verb and resource: 'Compare an ad group's performance metrics against the mean of its campaign sibling ad groups.' It clearly distinguishes this tool from related siblings like nevent_get_paid_ad_group_insights by framing it as a comparative sibling analysis rather than a plain metrics fetch.

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 gives explicit use context ('Use to detect underperforming ad sets'), a dependency guideline ('Use after nevent_list_paid_ad_groups to get a valid adGroupId'), and a troubleshooting path for 404s ('call nevent_paid_ads_health to confirm'). It does not explicitly state when not to use it or name an alternative tool, so it falls just short of a 5.

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?

Annotations already state readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: date-range defaults, daily row granularity, ISO 8601 UTC date format, and a specific 404 condition tied to the insights pilot. This goes well beyond the annotations and schema.

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?

Four sentences, each carrying distinct information: what the tool returns, how to get a valid ID, date defaults, metric list and date format, and an edge-case fallback. No filler or redundancy.

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

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

With no output schema, the description must explain return values, and it does with a metric list and timestamp format. It also covers prerequisite calls, default ranges, and a likely error path. This is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying date default behavior ('last 7 days when from/to are omitted'), the meaning of row.date, and reinforces the adGroupId prerequisite. This elevates it above baseline, though much parameter detail already lives 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 uses a specific verb and resource: 'Get daily performance metrics for a specific ad group (ad set).' It clearly identifies the granularity (ad group vs. campaign) and lists the exact metrics returned, distinguishing this tool from sibling campaign-level or comparative-stat 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?

It explicitly instructs 'Use after nevent_list_paid_ad_groups to get a valid adGroupId' and explains the default date range behavior. It also tells the agent to call nevent_paid_ads_health on a 404. It does not explicitly enumerate when NOT to use it relative to campaign-level insights, but the prerequisite and error-handling guidance are clear.

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?

Annotations already mark this as read-only and non-destructive. The description adds value by enumerating the returned fields and, importantly, disclosing a specific failure mode ('A 404 may mean this tenant is not enrolled in the insights pilot'). This goes beyond the safety hints and helps agents handle errors correctly.

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, then gives the prerequisite, the expected return payload, and an error-handling note. Every sentence earns its place; no filler or tautology is present, and the output enumeration is justified by the absence of an output schema.

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 getter with no output schema, the description covers the necessary context: how to obtain a valid ID, what the tool returns in detail, and what to do on the most likely error. The schema handles provider and parameter constraints, so nothing essential is missing.

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%, and the parameter descriptions already define provider as an enum and adGroupId with instructions to use nevent_list_paid_ad_groups. The tool description mostly repeats this prerequisite rather than adding new semantic meaning, so it meets the baseline but does not exceed it.

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 opens with a specific verb and resource: 'Get the full audience targeting configuration for an ad group.' It clearly identifies what the tool returns and is distinct from sibling tools like insights or comparative stats, even naming related tools for context.

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

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

It explicitly says to use it after nevent_list_paid_ad_groups to obtain a valid adGroupId, and it provides a concrete fallback: if a 404 occurs, call nevent_paid_ads_health to confirm pilot enrollment. This gives the agent clear when-to-use and alternative-routing 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?

Annotations already declare readOnlyHint and non-destructive, and the description adds substantial behavioral detail beyond that: daily row shape, metric names, ISO 8601 date format, default 7-day window, and a 404 pilot-enrollment caveat. There is no contradiction between description and 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?

Five sentences, each carrying distinct useful information: purpose, sequencing, defaults, return shape, date format, and 404 behavior. The core action and prerequisite are front-loaded, with no filler.

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?

With no output schema, the description correctly takes on the burden of explaining return values and error cases: it lists the metrics, specifies the timestamp format, documents the default date range, and provides a fallback diagnostic tool for 404s. This is fully complete for a read-only insights tool with fully documented parameters.

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 defaults, the provider enum, and campaignId provenance. The description restates the list-first requirement and date defaults, but adds little parameter-specific meaning beyond what the schema provides. The baseline 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 opens with 'Get daily performance metrics for a specific paid campaign,' a specific verb+resource statement. The qualifiers 'paid' and 'daily' plus the listed metrics distinguish it from the many sibling campaign-analytics tools. The specificity makes the tool's scope immediately obvious.

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?

It gives clear usage context: call nevent_list_paid_campaigns first to get a valid campaignId, and it routs a 404 to nevent_paid_ads_healthe. However, it never explicitly contrasts with sibling insights tools such as nevent_get_campaign_insights or gives a when-not-to-use condition.

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?

Annotations already declare readOnlyHint and non-destructive behavior, so the description is not required to repeat safety. It adds useful output context beyond annotations: the returned filter definition details, estimated contact count, and metadata. This is helpful because there is no output schema.

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?

Three sentences, front-loaded with the outcome, followed by usage direction and next steps. Every sentence earns its place with no redundant filler.

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-only tool, the description covers what is returned, when to call it, and what to do next. With no output schema, the description provides adequate return-value context and no critical information is missing.

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 coverage is 100%: segment_id is fully described with a regex pattern and guidance to get valid IDs from nevent_list_segments. The description adds no additional parameter semantics, but the schema carries the load, so baseline 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 uses a specific verb ('Retrieve') and names the exact resource: a segment's complete filter definition including criteria stanzas, operators, values, plus estimated contact count and metadata. It also differentiates from siblings like nevent_list_segments and nevent_segment_preview by placing this tool in the workflow.

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?

It gives explicit workflow context: call after nevent_list_segments, and next steps of nevent_segment_preview or nevent_update_segment. It also names concrete use cases (inspect, clone, explain a segment's logic), so an agent knows exactly when to invoke it.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Returns' framing is consistent with that read-only profile. The description adds value beyond the annotations by disclosing the warm-up phase vocabulary (cold/warming/warmed) and the warning condition that should trigger when the profile is unvalidated or still in warm-up — decision-relevant behavior the annotations cannot convey.

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?

Four sentences with no wasted words: when to call, what is returned, the warning behavior, and the companion tool. The primary use case is front-loaded ahead of the return-value list, so an agent scanning the first sentence already knows why this tool exists.

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?

With no output schema and zero parameters, the description carries the full burden of return-value disclosure — and it delivers by enumerating domain validation status, warm-up phase, send rate cap, and throttle settings. An agent has everything needed to decide when to invoke it and how to interpret the result, including a caveat condition.

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 zero parameters and schema coverage is 100%, so the 0-params baseline of 4 applies — there is nothing to document. The description instead clarifies what the caller receives, which is the semantically meaningful content for this tool.

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?

States a specific action ('verify the tenant is ready to send email') tied to an explicit resource (the tenant sending profile), then enumerates the returned data: sender domains and validation status, warm-up phase, send rate cap, and throttle settings. The 'before creating a campaign' framing distinguishes it from the many sibling get/list tools, and it is further differentiated from nevent_get_suppressions_summary, which is called out by 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?

Gives an explicit when-to-call rule ('before creating a campaign') and a conditional downstream action ('warn the user before scheduling a large campaign' if the profile is not validated or still warming). It also names the sibling to combine with (nevent_get_suppressions_summary) for a full deliverability health check, so an agent is never left to infer placement.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by enumerating the exact fields returned (id, shortCode, clickCount, etc.) and the relationship to other tools (use returned id with metrics). It does not contradict annotations and provides behavioral context beyond the structured data.

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

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

Two sentences with no filler. The first sentence states the purpose and included content; the second lists key fields and points to the metrics tool. All information is front-loaded and 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 simple read operation with one parameter, the description is complete: schema covers the parameter, annotations cover safety, and the description lists all returned fields (since there is no output schema) and explains the usage sequence. No critical information is missing for an agent to call this 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?

The input schema already covers the single parameter 'id' with a full description including format and source ('Obtain from nevent_list_short_urls response field "id"'). The description repeats this same guidance without adding new meaning, so the baseline of 3 applies given the 100% 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?

States a specific verb ('Get') and resource ('complete details of a specific short URL') and enumerates the content (target URL, metadata, dates, tags, click count). Clearly distinguishes from siblings like nevent_list_short_urls (which lists, not details) and nevent_get_short_url_metrics (which is for analytics, not 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?

Explicitly instructs to call after nevent_list_short_urls to obtain the id, and directs to nevent_get_short_url_metrics for time-series analytics. This provides clear sequencing and routes to the appropriate alternative tool, leaving no ambiguity about when to use this tool vs. 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds meaningful behavioral context by clarifying that aggregation spans ALL child user links, that it returns campaign-level totals and per-user breakdowns, and that it requires a parent short code. No contradiction with 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 appropriately sized and front-loaded: first sentence states the core behavior, second gives the usage context, third enumerates useful return fields since there is no output schema, and fourth clarifies the sibling boundary. Each sentence earns its place with no redundancy.

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

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

For a read-only aggregation tool with no output schema, the description is complete: it names the full set of return fields, explains the required input and its provenance, gives the typical use case, and routes the agent to the correct alternative when needed. Nothing critical for correct invocation is missing.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds extra value by telling the agent where to obtain parentShortCode (from nevent_list_short_urls where isParent=true) and reinforcing that it is the campaign parent code. This goes beyond the schema's field description, though days and topN semantics are left to 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 opens with a specific verb-resource pair: 'Get aggregated click metrics across a parent short URL and all its per-user variants.' It clearly distinguishes from sibling nevent_get_short_url_metrics by emphasizing aggregation across child links, so an agent can tell them apart immediately.

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?

It explicitly states when to use the tool: after a marketing campaign with per-user tracking links, and even names the creating tool (nevent_create_bulk_user_short_urls). It also directs the agent to the alternative, nevent_get_short_url_metrics(id), when a per-link breakdown is needed, which fully addresses when-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?

No annotations are present, so the description carries the behavioral disclosure burden. It discloses ordering ('ordered by most recent first'), default result size ('Default returns 100 most recent clicks'), adjustability via limit, and enumerates all returned fields. It does not mention rate limits or authentication, but for a read-only operation this is adequate.

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 three sentences, front-loaded with the core action and scope. The field enumeration is long but earns its place because there is no output schema to document return values. No filler or redundant phrasing.

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?

Without an output schema, the description compensates by listing all return fields, stating ordering, and explaining default limit behavior. It omits pagination details beyond the limit parameter, but that is a minor gap for a single-URL read tool with only two parameters.

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 meaningful context by explaining how to obtain the `id` ('Use after nevent_list_short_urls to get the id') and clarifies the limit behavior (default of 100, adjustable), which goes beyond the raw schema definitions.

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

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

The description states a specific verb ('Get'), a specific resource ('individual click event records'), and a scope ('for a specific short URL'). This clearly distinguishes it from siblings like nevent_get_short_url_metrics (aggregated metrics) and nevent_list_short_urls (URL listings) by emphasizing the 'individual click event records' granularity.

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?

Provides explicit sequencing guidance ('Use after nevent_list_short_urls to get the id') and enumerates use cases ('detailed click attribution, fraud detection, or per-user behavior analysis'). It does not explicitly name alternatives or when-not-to-use conditions, but the context is clear enough for an agent to route correctly.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: the tool returns aggregated metrics, uses a default 30-day window, and enumerates the exact dimensions and aggregates returned. This goes beyond what annotations capture.

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 information-dense without being bloated. It front-loads the core purpose and prerequisite, then lists return fields, then gives the primary use case and alternative. 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?

Given no output schema, the description compensates by listing all key return fields and dimensions. It also covers how to obtain the required id, the meaning of the optional `days` parameter, and the sibling tool to use instead for campaign-level metrics. Nothing essential for a read-only metrics tool is missing.

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 `id` and `days` fully, including defaults, bounds, and suggested values. The description reinforces the id origin and default window, but adds little semantic value beyond the schema; therefore the baseline 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?

States a specific verb ('Get'), a specific resource ('aggregated click analytics for a specific short URL'), and a clear scope ('over a time window'). It also distinguishes itself from the campaign-level sibling by explicitly naming nevent_get_short_url_campaign_metrics and limiting this tool to individual tracking links.

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?

Provides explicit sequencing guidance: use after nevent_list_short_urls to obtain the `id`. It also gives the exact use case ('performance analysis of individual tracking links') and names the alternative for campaign-wide aggregation. The agent receives clear when-to-use and when-not-to-use direction.

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?

Annotations already cover read-only and non-destructive behavior. The description adds useful context beyond annotations: it limits the result to the active tenant, specifies what the snapshot contains, and defines a 2% suppression-rate threshold that should be surfaced as a warning. It does not detail the response format, but the stakes are low for a read-only, zero-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?

Three sentences with no filler: the first states what the tool returns, the second gives call conditions, and the third adds the actionable threshold. The useful 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 zero-parameter read-only snapshot with no output schema, the description fully covers what the agent needs: what the tool returns, when to call it, and how to interpret the result. Nothing essential is missing.

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 zero parameters and no schema burden, so the baseline is 4. The description nevertheless communicates the data returned, which is all an agent needs to invoke the tool.

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 opens with a specific verb and resource: 'Get a deliverability health snapshot for the active tenant' and enumerates the returned breakdown (total suppressed emails, 30-day trend, reason breakdown). The scope is distinct from the sibling analytics and campaign tools, so an agent can identify this as the suppression/list-health tool without opening other definitions.

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?

It gives explicit when-to-use guidance: 'Call this when the user asks about list health, unsubscribe rates, or bounce issues.' It does not explicitly name alternative tools or state when not to use it, which keeps it just below a 5.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing exactly what data will be retrieved (MJML source, rendered HTML, tags, usage metrics), which is useful behavioral context beyond the annotations. It does not mention any potential side effects or limitations, but these are not pertinent given the read-only nature. No contradiction with 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 a compact, front-loaded paragraph that opens with the core action and return values, then provides sequencing context and next steps. Every sentence contributes meaningful information with no redundancy or fluff. It is appropriately sized for the tool's simplicity.

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-only tool with full schema coverage and no output schema, the description is complete. It specifies what is returned, when to call it, and what to do next. An agent has all necessary information to decide when and how to invoke it correctly, without needing additional details.

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 coverage is 100%: the template_id parameter has a description that explains its purpose and how to obtain valid IDs (from nevent_list_templates). The tool description does not add any additional parameter semantics beyond what the schema already provides. Since the schema fully documents the parameter, the baseline of 3 is correct.

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 ('Retrieve') and the resource ('email template'), and enumerates the specific content returned (MJML source, rendered HTML, tags, usage metrics). It distinguishes itself from sibling tools by explicitly framing the retrieval as the second step after nevent_list_templates and before nevent_update_template or nevent_create_campaign, making its role in the workflow 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 gives explicit when-to-use context: 'Call this after nevent_list_templates when the user wants to inspect, copy, or modify a template.' It also names the next-step alternatives (update or create campaign). It does not explicitly mention when not to use it (e.g., if only a preview is needed, nevent_preview_template might be more appropriate), but the guidance is clear enough for typical usage. A score of 4 is appropriate given the lack of explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context by stating it returns structured markdown and that omitting the topic yields an index of all topics. No contradictions with the annotations.

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

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

Three sentences, no filler. The main purpose is front-loaded, concrete topic examples are compact, and the fallback behavior (omit topic) is stated at the end. 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 single-optional-parameter help tool with no output schema, the description is complete: it explains the return format, the available topic categories, example values, and the index behavior. An agent has everything needed to invoke it 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 coverage is 100%, so the parameter is well documented already. The description adds value beyond the enum by explaining what each key topic category means (workflows, errors, tenants) and by giving examples like paid_media/analytics/segments, which helps the agent map intent to the right topic value.

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

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

The description uses a specific verb ('Get guidance') and clearly defines the resource: guidance for tool selection and error handling. It also distinguishes itself from the sibling domain tools by positioning itself as the meta-help tool, so an agent can tell it apart from the many analytics/campaign/segment tools without inspecting them.

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: when unsure which tool to call or how to handle an error. It also provides concrete topic routing examples (workflows, errors, tenants, paid_media, analytics, segments) and tells the agent to omit topic to get an index, which is clear guidance for a help 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavior beyond that: it returns a paginated envelope with content, page, size, totalElements, and totalPages; it flags that rows contain personal data; and it advises requesting the smallest page and filtering rather than paginating through everything. This is strong supplementary context with no contradiction.

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 purpose and contains no wasted sentences, but it is dense and the final privacy warning makes it somewhat long. Still, every sentence earns its place by adding either usage guidance or behavioral context.

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 paginated list tool with no output schema, the description covers the return envelope, recipient-row content, filtering strategies, pagination behavior, privacy constraints, and even where to get related IDs. An agent has enough to call and interpret 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 coverage is 100%, but the description still adds meaning beyond the schema: it frames status as a way to see who bounced/clicked/unsubscribed, segment_id as narrowing to one audience on multi-segment campaigns, search as finding one person by name/email, and page_size as a privacy/context concern. This is genuine usage semantics, not repetition.

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 opens with a specific verb and resource: "List the individual recipients of a campaign and what happened to each message." It clearly differentiates this from aggregate metrics by saying it puts "names behind the aggregate numbers from nevent_get_campaign_metrics," so an agent can distinguish it from the sibling metrics tool.

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?

Usage is explicit: use this to see recipient-level detail behind aggregate numbers, and it names the alternative tool (nevent_get_campaign_metrics). It also gives concrete selection guidance for status, segment_id, and search, telling the agent when each filter 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds transparency about what the tool returns (top-level metrics, not full content), scopes it to the active tenant, and signals that further detail requires other tools. No annotation contradiction exists.

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 compact and front-loaded with purpose, followed by return shape, filtering, and follow-up routing. It is well structured overall, though the filter sentence loses some credit because it contains inaccurate enum values.

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 output schema, the description adequately explains what is returned, the active-tenant scope, and how to proceed to related tools. It falls short of 5 mainly because the misleading status and channel examples could lead to incorrect calls, and the description does not fully reconcile its filter values with the schema.

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 coverage is 100%, so the baseline is 3, but the description's filter guidance is inaccurate: it lists status values DRAFT/SCHEDULED/SENT/FAILE D while the schema enum is EXECUTED/DRAFT/PAUSED/STOPPED/SCHEDULED, and lists channel EMAIL/SMS while the schema includes WHATSAPP. This can actively mislead an agent into sending invalid parameter values, outweighing the minor interpretive value it adds.

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 opens with a specific purpose: discovering existing campaigns before reporting or scheduling, which clearly names the resource and intended action. It also states the returned fields (status, channel, send date, top-level metrics) and distinguishes itself from the deeper follow-up tools nevent_get_campaign and nevent_get_campaign_insights.

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?

It explicitly tells the agent when to call: before performance reporting or scheduling new sends. It also provides concrete routing guidance, saying to use the returned campaign id to call nevent_get_campaign or nevent_get_campaign_insights for deeper 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's read-only nature aligns. The description adds meaningful behavioral context beyond annotations by specifying the exact returned fields (src URL, file name, MIME type, size in bytes) and the tenant-scoped listing behavior. This is useful for an agent deciding whether the tool satisfies a request.

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 three sentences with no filler. The main purpose is front-loaded, the output fields are listed compactly, and the usage guidance is specific and actionable. 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 zero-parameter read-only listing tool, the description is complete. It names the resource scope (Nevent media library, current tenant), the exact return fields, and how to use the returned values. Since there is no output schema, the description fully compensates by enumerating the important output attributes and downstream usage.

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 zero parameters, so there is nothing for the description to explain about parameter semantics. The provided baseline of 4 applies because the parameter space is empty and no parameter guidance is needed. The description focuses instead on the output, which is appropriate for a no-input list operation.

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

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

The description states a specific verb and resource: "List all images stored in the Nevent media library for the current tenant." It also clarifies the scope to the current tenant, which distinguishes it from broader list tools. The output fields are enumerated, leaving no ambiguity about what the tool does.

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 clearly establishes the context: retrieving media binary metadata for the current tenant. It also gives downstream usage instructions for the returned src value, including using it in email templates or passing it to nevent_delete_image. It does not explicitly name the alternative tools it competes with, but the context is clear enough.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context by listing the returned fields (ID, name, status, lastSyncedAt) and confirming it is a read-only drill-down operation. No contradiction with 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?

Three tightly packed sentences, each earning its place: the core action, the workflow position, and the downstream usage. No fluff or repetition.

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-only list tool, the description covers what it returns, how to filter, and how to chain results into subsequent tools. The output schema is absent, but the description names the return fields, which is sufficient for this 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%, with the provider enum fully documented and campaignId already described as an optional filter referencing nevent_list_paid_campaigns. The description essentially repeats schema guidance without adding deeper parameter semantics, so it meets the baseline but does not exceed it.

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 lists ad groups/ad sets for a paid ads provider, with an optional campaign filter. It explicitly differentiates from related siblings like nevent_list_paid_campaigns and nevent_list_paid_ads by naming its resource and position in the workflow.

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 instructs to use this after nevent_list_paid_campaigns for drill-down, and tells the agent to feed returned adGroupId values into the ad group insights, targeting, and comparative stats tools. It does not explicitly state when not to use it in favor of a sibling, so it falls just short of a 5.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds useful behavioral context about drill-down flow and returned fields, but does not mention potential pagination, rate limits, or provider-specific behavior. The description adds some value beyond annotations without providing deep behavioral detail.

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

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

Four short sentences, each with a distinct purpose: state the action, position the tool in the workflow, list return fields, and provide the follow-up action. It is front-loaded with the core purpose and contains no filler or redundant restating of the tool name.

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 filtered list tool with a required provider enum and optional parent IDs, the description is complete: it explains the workflow, names the valid ID sources, and lists the returned fields, which is especially valuable because there is no output schema. No essential calling information is missing.

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 parameters are already documented in the schema. The description reinforces that campaignId and adGroupId are optional filters and connects them to sibling tools, but adds no new parameter-level meaning such as format, constraints, or interactions. A baseline score of 3 is appropriate.

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

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

The description opens with a concrete verb and object: 'List individual ads for a paid ads provider.' It also differentiates the tool from siblings by scoping it to the ad level, after listing campaigns or ad groups and before retrieving creative. This makes its role in the paid-ads workflow 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 sequences the tool: 'Use after nevent_list_paid_campaigns or nevent_list_paid_ad_groups to drill down to ad level.' It also tells the agent what to do with the results: 'Use the returned adId values with nevent_get_paid_ad_creative.' This is clear when-to-use guidance tied to named sibling 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the tool returns campaign IDs, names, statuses, objectives, and budgets, and by clarifying the data are 'synced from a provider'. It does not mention pagination or absence of filtering, but given the simple read-only nature and annotation coverage, this is a solid disclosure.

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 compact and efficient. The first sentence states the action, the second gives the call rationale, the third summarizes the output fields, and the fourth connects to downstream tools. Every sentence earns its place and there is no redundant filler.

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

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

This is a low-complexity tool with one required enum parameter and no output schema. The description covers the purpose, the parameter, the return fields, and the follow-up tools, so an agent has everything needed to select and invoke it 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%: the provider parameter is fully documented with an enum of meta, google, and tiktok. The description repeats the provider values in prose without adding syntax, format, or behavioral meaning beyond the schema, so the baseline 3 applies.

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 begins with a specific verb-resource pairing: 'List all paid campaigns synced from a provider', explicitly enumerating meta, google, and tiktok. It distinguishes this from other campaign-list tools by emphasizing 'paid campaigns synced from a provider' and even names the downstream tools that consume its campaignId output, so an agent can disambiguate it clearly.

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?

Usage guidance is explicit: 'Call this to discover campaignId values — you need a campaignId to call insights or ad group tools.' It then tells the agent exactly what to do with the returned values by naming nevent_get_paid_campaign_insights and nevent_list_paid_ad_groups. This goes beyond mere context and gives actionable routing.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that results are scoped to the active tenant and by enumerating the returned fields, which is helpful given there is no output schema.

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?

Three tight sentences with no filler. The first sentence front-loads the primary call-to-action, the second states the return data, and the third provides follow-up tool routing. 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 zero-parameter, read-only list operation, the description is complete: it explains when to invoke it, what it returns, and what to do with the results. The absence of an output schema is mitigated by listing the returned fields 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?

The tool has zero parameters and an empty input schema, so there is no parameter ambiguity to resolve. The description correctly avoids inventing parameters and instead focuses on the return contract, which is the only semantically relevant information.

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

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

The description states a specific action: returns all saved segments for the active tenant, and lists the exact fields returned (id, name, estimated contact count, last-execution date). It clearly distinguishes this tool from segment-related siblings by framing it as the entry point and naming downstream 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 opening phrase 'Call this FIRST when you need to build or target an audience' explicitly prescribes when to use the tool. It also provides concrete routing guidance: use returned segment ids to call nevent_get_segment, nevent_segment_preview, or nevent_create_campaign, clarifying how it fits into the broader workflow.

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?

The description adds substantial behavioral detail beyond the readOnly/destructive annotations: campaign parents collapse into single rows, totals are aggregated, assistant links are included and flagged readOnly=true, and pagination is over groups rather than documents. This gives an agent an accurate model of what the tool actually returns and what to avoid doing with read-only rows.

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 dense but every sentence earns its place: purpose, distinguishing use case, aggregation behavior, read-only caveat, filtering, and follow-up drill-down paths all appear in a logical, front-loaded order. Despite its length, there is little redundancy and no filler.

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?

With no output schema, the description fills the gap by naming the key output fields (totalClicks, linksCount, campaignsCount, canonicalId, members[]) and clarifying pagination semantics. Combined with the fully described parameters, an agent has enough context to select and invoke 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 schema already documents all four parameters. The description reinforces the meaning of origin and pagination but does not add significant semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List short links grouped by DESTINATION URL', and immediately distinguishes itself from nevent_list_short_urls by explaining that it returns one row per destination rather than per link. This makes the tool's unique role unmistakable.

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?

It gives an explicit use case ('how much traffic is this landing page getting across all my campaigns?') and directly explains why the sibling nevent_list_short_urls cannot answer it. It also notes when assistant links are included and how to drill deeper, offering clear guidance on when to use this tool 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the tenant scope, the pagination envelope, the key item fields, and how IDs and shortCodes tie into related tools.

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 fairly dense but not bloated; each sentence contributes either the core purpose, return shape, key fields, or filter behavior. It could be tightened slightly, but the structure is logical 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?

Because there is no output schema, the description correctly explains the return envelope (items, total, page, pageSize, totalPages) and highlights important item fields. It also provides cross-references to metrics and click-count tools, making it self-sufficient for an agent deciding how to call and use the result.

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 already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that search filters by title or URL and that isActive=true isolates active links, which supplements 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 action ('List all short URLs'), the resource scope ('for the current tenant'), and the included tracking metrics. It also names concrete use cases and key fields that distinguish it from related URL tools like nevent_get_short_url or nevent_list_short_url_destinations.

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?

It explains when to use the tool: discovering existing campaign links or auditing active tracking URLs. It also gives practical filter guidance for isActive and search, though it does not explicitly state when to prefer a sibling tool instead.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with a read-only list operation. It adds useful behavioral context by stating the result is an array of ShortUrlDTO with userId, shortCode, shortUrl, and clickCount, and that the returned ids feed into nevent_get_short_url_metrics.

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 two sentences, front-loads the core purpose, and then packs usage context, prerequisite, return shape, and downstream usage without waste. 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?

Despite having no output schema, the description names the return type and its key fields, which covers what an agent needs. For a single-parameter read-only tool, the prerequisite sourcing and clear use cases make the context 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?

Input schema coverage is 100%, and the schema already explains the parentShortCode pattern and how to obtain it from nevent_list_short_urls. The description repeats this dependency but adds no substantially new parameter meaning, so the baseline 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 opens with 'List all per-user short URL variants created under a parent (campaign) short URL', which is a specific verb, resource, and scope. It clearly distinguishes this tool from sibling list tools like nevent_list_short_urls and from creators like nevent_create_bulk_user_short_urls.

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?

It gives explicit use cases: after nevent_create_bulk_user_short_urls to inspect generated links, or to audit which users have a tracking link. It also states the required input provenance — parentShortCode from nevent_list_short_urls where isParent=true — so an agent knows exactly when and after what to call it.

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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results are scoped to the active tenant, and the tool returns only template metadata, not the full source. The pointer to nevent_get_template implicitly discloses that this tool does not return the full source, which exceeds the annotation baseline.

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?

Four short sentences, each earning its place: when to call, what it returns, how to use the result, and which sibling to call for full source. There is no fluff or redundancy, and the primary purpose 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?

Because there is no output schema, the description's list of returned fields (id, name, tags, MJML/HTML) is valuable and largely sufficient. It also explains the tool's role in the campaign-creation workflow with clear links to sibling tools. It does not mention pagination metadata or whether sortable timestamps are included in the response, but the schema's limit and sort parameters cover the mechanical aspects.

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 describes all five parameters with full coverage, including defaults, enums, and semantics, so the baseline is 3. The description does not repeat or expand on parameter behavior such as tag filtering or content_nature. No additional semantic value is added 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 states a specific action, 'discover available email templates before creating a campaign,' and enumerates the returned data (id, name, tags, MJML/HTML format). It clearly distinguishes from nevent_get_template by framing this as the list-level discovery tool and the sibling as the full-source inspector. The active-tenant scoping provides a precise resource boundary.

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?

It explicitly frames when to call the tool: before creating a campaign. It also gives an alternative path by instructing the agent to call nevent_get_template for full HTML/MJML source, and shows how the returned id feeds into nevent_create_campaign. This provides clear when-to-use and when-to-use-a-different-tool 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?

Annotations already declare readOnlyHint and destructiveHint, and the description adds meaningful role-based behavior: SUPERADMIN sees all tenants while OWNER/ADMIN sees a limited hierarchy subtree. It also discloses the return fields (tenant IDs and names), which is useful beyond the structured 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?

Three concise sentences deliver purpose, output, and role-based behavior with no redundancy. The most important information is front-loaded, and each sentence adds value.

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 no-parameter read-only list tool, this description is complete: it states what is returned, who sees what, and how the result is meant to be used. The absence of pagination or response-format details is not a material gap given the simplicity and available 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 tool has zero parameters and schema coverage is complete, so the description has no parameter burden. The baseline of 4 applies, and the description appropriately focuses on behavior and output rather than nonexistent inputs.

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?

Description uses a specific verb ('List') and resource ('all Nevent tenants accessible to the authenticated user'), and clarifies that tenants are clients. It clearly differentiates from sibling tools by tying the output to nevent_switch_tenant and specifying role-dependent scope.

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 the intended use case: obtaining tenant IDs and names for use with nevent_switch_tenant. It provides clear context about when to call the tool, though it does not explicitly mention when not to use it or identify alternative listing 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral context: it explains the meaning of key fields like throttle.isThrottled and featureGate.isInTenantAllowlist, and it explicitly documents the 404 case as 'tenant is not enrolled in the insights pilot.' This is valuable transparency, though it does not describe the full response envelope or other possible 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 compact and front-loaded: the first sentence states the core purpose, the second gives an immediate usage directive, the third lists the key return fields, and the fourth documents a critical 404 behavior. Every sentence earns its place without redundancy or fluff.

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

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

Given the tool's simplicity—one enum parameter and no output schema—the description covers the essential context an agent needs: what the tool returns, key field meanings, and what a 404 indicates. It is nearly complete, though it could also mention the expected shape of the full response or whether the listed fields are always present.

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 already provides 100% coverage for the single provider parameter, including an enum and description. The tool description adds no additional parameter-level semantics, so it does not need to compensate. A baseline score of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Get operational health signals for a paid ads provider' and enumerates the specific signals it surfaces: throttle state, feature gate enrollment, stale syncs, and tier. It is specific enough to distinguish from general analytics tools, but it does not explicitly differentiate itself from the similarly named sibling nevent_paid_ads_status.

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 gives a strong, explicit usage directive: 'Always call this before claiming "no data" to the user.' It also explains what signals the tool surfaces, which helps an agent decide when to consult it. However, it does not mention when not to use it or name any alternative tools for comparison.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not burdened with safety disclosure. It adds meaningful behavioral value by specifying the return shape (connected, accountId, accountName, lastSyncAt) and the recommended call ordering, which goes beyond the schema.

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 compact and front-loaded. The first sentence states the purpose, the second gives usage guidance, and the third lists the return fields. Every sentence earns its place with no 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-only tool with no output schema, the description covers the purpose, usage context, and return fields. Minor gaps exist, such as not explaining behavior when connected=false or differentiating from nevent_paid_ads_health, but overall it is sufficient.

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% because the provider parameter is fully described with an enum and explanation. The description merely repeats 'meta, google, or tiktok' without adding new meaning, so the baseline of 3 applies.

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 'Check' and the resource: whether a paid ads provider account is connected to the tenant and the last sync time. It is clear and specific, but it does not explicitly name or contrast a sibling tool, so it falls short of a 5.

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 gives explicit guidance: 'Call this first before any ads queries to confirm the integration is active.' This is a clear context for use, though it does not discuss alternatives or when not to use the tool, so it misses the top 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the UTM matching mechanism, that results are per-campaign, and the exact return fields. There is no contradiction between the description and 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?

Three sentences, each with a distinct job: purpose and mechanism, return fields, and usage context. The most decision-relevant information is front-loaded, and there is no filler or repetition of schema details.

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

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

For a single-parameter read-only tool with no output schema, the description is quite complete: it states the return fields, the UTM-based matching behavior, the use case, and an ordering hint relative to nevent_list_paid_campaigns. Minor gaps like field types or edge cases (e.g., campaigns without UTM matches) are not critical given the tool's low 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 provider parameter fully documented via enum values (meta|google|tiktok) and a clear description. The tool description does not add parameter-specific detail, but the schema already carries the full meaning, so a baseline 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 states a specific verb ('Get') and a specific resource ('most business-focused view of paid ads'), and explains the mechanism: linking campaigns to ticket sales and revenue via UTM matching. It distinguishes itself from sibling tools like nevent_get_paid_campaign_insights by emphasizing business metrics (ticketsSold, revenue, budget) rather than raw ad-platform metrics.

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 says 'Use this when the user asks about ROI, conversion, or revenue from paid ads' and instructs to use it 'after nevent_list_paid_campaigns to cross-reference campaign IDs.' It provides clear contextual triggers and even an ordering rule, but it does not explicitly state when not to use it or name alternatives, which keeps it just shy of a 5.

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?

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description adds substantial behavioral context beyond that: the exact return shape (raw vs personalized body, detected merge tags), the dual-mode behavior (providing a sample user vs omitting both params yields raw tags only), and sample_user_id priority semantics. No output schema exists, so this behavioral disclosure carries real weight.

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?

Three sentences, each earning its place: purpose, return values, then workflow/parameter guidance. Zero fluff, and the most decision-relevant fact (call before send_test_template) is prominently placed.

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?

Complete for a read-only preview tool: no output schema exists, but the description explains return values; the required param is documented in schema; the two personalization modes are covered; and the relationship to its workflow sibling is explicit. The only conceivable gap (behavior on unresolvable sample_user_email) is a minor edge case.

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%, and the individual parameter descriptions are rich (example subject line, tenant-scoped email lookup, priority ordering, omit-to-get-raw behavior). The description mostly restates what the schema already says about sample_user_id/sample_user_email, adding a compact framing but no genuinely new parameter insight.

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?

Starts with a specific verb+resource+mechanism ('Preview a template with merge tags resolved against a sample user's profile'), which immediately distinguishes it from siblings like nevent_get_template (fetch), nevent_update_template (mutate), and nevent_send_test_template (send). The return values (originalBody, personalizedBody, detectedMergeTags) further pin down what the tool does.

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?

Gives explicit workflow guidance: 'Always call before nevent_send_test_template to validate rendering.' This tells the agent when in a sequence to use the tool. It does not explicitly state when NOT to use it or name routing alternatives such as nevent_get_template for plain template retrieval, but the sequencing rule is clear and 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?

Annotations already mark the tool as readOnly and non-destructive, and the description reinforces this with 'it never debits credits and never sends.' It also discloses important edge-case behavior: the audience block is null for WhatsApp channel mixes, more than 20 segments, or data-api timeout, while cost and recipientCount remain valid. This is valuable non-obvious context beyond the annotations.

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

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

The description is long but dense, and every sentence earns its place. The most critical facts — purpose, safety, and workflow position — are front-loaded, followed by return fields and caveats. Since there is no output schema, the detailed enumeration of returned fields is necessary rather than redundant.

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?

With no output schema, the description fully covers the return contract: cost, available, missing, recipientCount, affordable, blocked, unlimited, and the detailed audience block structure. It also explains the null-audience failure mode and confirms that cost remains valid in that case, making the tool interpretable end-to-end.

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 meaningful extra guidance by naming nevent_list_segments as the source for segment_ids, clarifying the omitting behavior ('omit them to quote the full addressable audience'), and giving concrete examples of genuinely transactional sends. This exceeds what the schema alone 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 begins with a specific verb and resource: 'Estimate the credit cost and eligible audience of a campaign BEFORE sending it.' It then clarifies this is a read-only pre-flight check against a specific endpoint, which distinguishes it from sibling tools like nevent_create_campaign and nevent_schedule_campaign.

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 call the tool: 'Call this after nevent_create_campaign and before nevent_schedule_campaign,' and explains the consequence of not doing so (402 failure at send time). It also directs the agent to source segment_ids from nevent_list_segments and gives guidance on when transactional=true 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?

The description discloses a meaningful behavioral trait beyond the annotations: 'no re-render triggered', which is not apparent from readOnlyHint=false or destructiveHint=true. It also states the return value ('Returns the updated template'). The destructiveHint is not elaborated, but the lightweight guarantee and return behavior add useful 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?

Three tight sentences with no fluff. The main purpose and key trait are front-loaded, followed by usage context and next steps. 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?

Given this is a simple 2-parameter rename operation with no output schema and annotations covering read-only/destructive hints, the description is complete: it explains what happens, when to use it, the return value, and what to do next. An agent has everything needed to call it 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%, and both parameters already have clear descriptions: name includes length rules and duplicate allowance, template_id includes a lookup hint. The description doesn't add new parameter-level detail, but the schema fully carries that weight, so baseline 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?

States a specific verb and resource: 'Rename an email template without modifying its content'. It distinguishes itself from update_template by emphasizing no content change and from clone_template by its rename purpose. The 'lightweight — no re-render triggered' clause makes the tool's unique role unmistakable.

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 tells when to use: 'Use after nevent_clone_template to give the clone a proper name, or to reorganize existing templates.' It also names the next steps for content changes and rendering validation. This is clear routing guidance with named 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?

The description reveals a non-obvious behavioral trait: 'tenant switches PERSIST in the user record in the database — this tool reverses that,' which goes beyond the annotations' readOnlyHint:false. It also explains the safety consequence of not calling it: 'avoid leaving your SUPERADMIN account pointing to another tenant'. This meaningful context helps the agent reason about side effects.

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

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

Four tightly packed sentences, each carrying distinct information: the core action, the mandatory usage rule, role-specific behavior, and the parameter note. It is front-loaded with the primary purpose and wastes no 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 state-resetting tool with no output schema, the description covers the critical operational details: when to invoke it, what it does for each role, and the persistence caveat for SUPERADMIN. An agent has everything necessary to call it correctly and understand the consequences.

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?

There are zero parameters, so the baseline is 4. The description adds the explicit confirmation 'No parameters needed,' which is a small but useful reassurance. Since the schema is empty and coverage is 100%, there is nothing more to explain.

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 opening verb 'Restore' plus 'original tenant context set at session start' states exactly what the tool does, and the explicit contrast with nevent_switch_tenant in the same description distinguishes it from the obvious sibling. The title 'Reset to home tenant' is a consistent shorthand. An agent can select this tool with no 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 gives an explicit rule: 'ALWAYS call this after cross-tenant queries (nevent_switch_tenant)'. It further qualifies behavior by user role (SUPERADMIN persistence vs OWNER/ADMIN/STAFF home reset), telling the agent exactly when the cleanup is required and why. The when-to-use instruction is unambiguous and directly tied to the sibling 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?

Even though destructiveHint is already true, the description adds critical detail: the campaign will be queued for sending to real contacts, confirmed=true requires explicit user consent, and the status changes from DRAFT to SCHEDULED. This goes well beyond the annotations.

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

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

The description is front-loaded with the purpose and the destructive warning, and each sentence adds useful context. It is somewhat longer than necessary because some constraints duplicate the schema, but it remains well-structured and readable.

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 strong annotations and full schema coverage, the description is complete: it covers preconditions, required confirmation, side effects, and the resulting status. Nothing essential is missing for correct 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 baseline is 3. The description reinforces constraints like future scheduled_time and DRAFT status, but mostly repeats what the schema already documents rather than adding new parameter-level meaning.

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

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

The description states a specific verb and resource: 'Schedule an existing DRAFT campaign for delivery at a specific ISO-8601 datetime.' It also clarifies the state transition from DRAFT to SCHEDULED, distinguishing it from create/send 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?

It gives clear usage context: only schedule existing DRAFT campaigns, use confirmed=true with explicit user consent, and call nevent_get_campaign first to verify content and recipient segment. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with those. It adds useful context by specifying that the response includes IDs, operators, and value types, but it does not disclose possible pagination, ordering, tenant scope, or the exact response envelope—especially relevant since there is no output schema.

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?

A single, front-loaded sentence that uses every word meaningfully. It names the verb, resource, scope ('all available'), and result contents without filler or redundancy.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies the essential information an agent needs: what is listed and what fields are included. The only minor gap is that it does not describe the response shape or any limits, but with no parameters and strong safety annotations, this is not a serious 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 input schema has zero parameters, which is the baseline-4 case; there are no parameter semantics for the description to clarify. The mention of IDs, operators, and value types describes the returned data rather than inputs, so it neither adds nor detracts from 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?

States a specific verb ('List') and resource ('audience segmentation criteria') and names the returned fields (IDs, operators, value types). This clearly separates it from siblings like nevent_list_segments, which lists saved segments, and nevent_analytics_filter_values, which lists filter values.

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

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

The description implies a reference-lookup use: call this to discover which segmentation criteria are available. However, it does not explicitly say when to use it before creating or editing a segment, nor does it name alternatives such as nevent_create_segment or nevent_get_segment. The intended usage is reasonably inferable but not explicit.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the retrieval/pagination behavior and is consistent with the annotations, so no contradiction. It does not disclose potential response size, rate limits, or behavior on invalid definitions, but with annotations covering safety, the bar is met.

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?

A single front-loaded sentence: the verb 'Execute' comes first, followed by the resource and the pagination qualifier. There is no filler, repetition of the schema, or extraneous detail — every word 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?

The tool is complex (nested DSL, 3 params, no output schema), but the schema documents it thoroughly and annotations cover the safety profile. The description covers the core contract (execute, return matching contacts, paginated). A minor gap is the absence of any hint about the response shape, since no output schema exists to fill that role.

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%, and the schema documents every parameter exhaustively, including the nested segment DSL (value types, operator rules, modifiers guidance, filters). The tool description adds little beyond flagging pagination, which the schema already covers. Baseline 3 applies when the schema carries the semantic burden.

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

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

The description states a specific verb and resource: 'Execute a segment definition and retrieve matching contacts with pagination.' The title 'Execute segment and get contacts' reinforces the action. This distinguishes it from siblings like create/get/update/list segment, which operate on segment definitions rather than executing them for 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?

No guidance is given on when to use this tool vs alternatives. The sibling `nevent_segment_preview` appears to overlap heavily in purpose, yet the description offers no selection criteria or exclusions. Usage is only implied by the tool's name, not stated.

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?

The description adds significant behavioral context beyond the readOnlyHint and destructiveHint annotations: it explicitly says the segment is not saved, returns an estimated size, provides a known limitation about combining attendance and spending criteria in the same stanza, and mandates modifier rules. This is valuable operational guidance an agent cannot derive from annotations or schema alone.

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 longer than average, but the complexity of the segment DSL justifies much of the length. The purpose is front-loaded, and every major rule is actionable; however, some details, such as entity array syntax and time_range.value > 0, are already present in the schema and are therefore somewhat redundant.

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 rich input schema, the readOnly/destructive annotations, and the absence of an output schema, the description fills the remaining gaps: it explains what the tool returns, that it has no persist effect, and provides the domain-specific constraint needed to construct a valid preview definition. It is sufficiently complete for an agent to invoke the tool correctly.

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

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 value types, operators, modifiers, and stanza semantics. The description reinforces the most failure-prone rules (single string OR array for ENTITY operators, omit modifiers unless requested, time_range.value must be > 0) and adds the critical non-obvious rule about separating attendance and spending criteria, which is 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 opens with a specific verb-resource pair: 'Preview estimated audience size for a segment definition without saving it.' It clarifies the tool is a read-only estimation action rather than a save or execute action, distinguishes it from siblings like nevent_create_segment and nevent_segment_execute, and states the concrete outputs (fan count and sample 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?

The description establishes clear context: use this when you need an audience estimate for a segment definition before saving or executing it. It does not explicitly name alternative tools or state when not to use it, but the 'without saving it' framing and sibling set make the intended usage inferable.

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?

It discloses meaningful behavioral details beyond the annotations: test emails carry test indicators in headers, delivery can take up to 60 seconds, and the call returns success status, recipient list, and error details. This complements the destructiveHint and readOnlyHint annotations without contradicting them.

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

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

The description is front-loaded and mostly efficient, with purpose, usage, behavior, and return value in a short paragraph. It loses a point for redundancy: SES is mentioned three times, slightly diluting the conciseness.

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

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

Given the rich input schema and no output schema, the description provides the essential missing context: when to invoke, side-effect expectations, latency, and return value summary. An agent can safely select and invoke this tool with the information 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?

Schema description coverage is 100%, so the baseline applies because the input schema already explains all six parameters. The tool description itself does not add parameter-level meaning beyond pointing out that test emails go to recipient addresses.

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 opens with a concrete verb and resource: it sends a test email of the template to one or more addresses via SES. It also anchors the tool in a workflow after nevent_preview_template, which helps an agent distinguish it from preview, scheduling, and campaign 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 clearly states when to use it: after nevent_preview_template validates rendering. However, it does not state when not to use it or name an alternative for production sends, so it stops short of fully explicit routing.

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?

Annotations already carry readOnlyHint=false/destructiveHint=false, so the description's job was to add real behavioral context—and it overdelivers. It discloses that SUPERADMIN invocations mutate the user record and PERSIST, that the same call is session-scoped for other roles, that reset is mandatory to avoid lingering state, and that OWNER/ADMIN/STAFF can only reach descendants within 3 hierarchy levels. This transforms a 'switch context' tool from potentially surprising to fully predictable. No annotation contradiction detected.

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?

Purpose first, effect scope second, then role-specific behavior in priority order, then the cleanup mandate, then the discovery pointer. Every sentence carries distinct, non-redundant information and the most safety-critical facts (persistence, reset) are front-loaded. Dense but not bloated.

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, no-output-schema state mutation tool, nothing needed by a caller is missing: the action, the side effects, the role conditions, the depth limit, the cleanup requirement, and the way to obtain valid IDs. The lack of an output schema is acceptable since a switch tool's return value is near-irrelevant next to the behavioral caveats the description already exhaustively covers.

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 coverage is 100%—the tenant_id param already restates session scoping, persistence warning, role limits, and the list_tenants pointer. With that coverage the baseline is 3. The description earns one additional point by supplying the 'max 3 levels deep' subtree constraint, which is absent from the schema and which materially affects whether a call will succeed.

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?

States a specific verb and resource ('Switch the active tenant for this session') and immediately defines the blast radius ('All subsequent queries... will use the specified tenant's data'). It separates the tool from siblings by naming nevent_reset_tenant and nevent_list_tenants and by clarifying exactly which tenant-refining behavior it introduces—a session-wide context change rather than a one-off query param.

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?

Gives explicit when-to-use and when-done guidance: 'Always call nevent_reset_tenant when cross-tenant work is done' and 'Use nevent_list_tenants to discover available tenant IDs.' Role-based conditions (SUPERADMIN vs OWNER/ADMIN/STAFF) read like a decision rule, so the agent knows not only when to call it but what to do before and after. This is the gold standard.

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?

Annotations already flag destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that this is a write operation. It adds valuable behavioral guidance beyond the annotations: inspect before changing and preview after updating. No contradiction exists between the description and 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 three sentences with no wasted words. The core action comes first, followed by the prerequisite workflow and the post-update verification step. 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?

Given the complex nested schema, the description supplies the missing workflow context: using get_segment for a safe update, the at-least-one requirement, and the preview follow-up. It does not describe return values, but no output schema exists and the preview instruction compensates for that gap. Overall, an agent has enough context to call this 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%, and the schema already explains segment_id, name, definition, and all nested DSL fields in detail. The description adds general mention of 'name and/or filter definition' but not deeper parameter semantics. Per the baseline for high schema coverage, this is adequate.

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 starts with a specific verb and resource: 'Modify an existing segment's name and/or filter definition.' It clearly states the exact scope of the operation and differentiates it from segment creation because it targets an existing segment. The action is unambiguous and aligns with the sibling tool set.

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 gives explicit workflow guidance: call nevent_get_segment first to inspect the current definition, provide at least one of name or definition, and call nevent_segment_preview afterward to verify the audience count. This tells the agent not only what to do but in what order, which is strong usage context.

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

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

Beyond readOnlyHint=false and destructiveHint=true, the description discloses partial-update semantics ('only provided fields are changed — omitted fields remain unchanged'), immediate effect, replace-vs-merge behavior for tags/metadata, the shortUrlDTO return value, and the exact READ_ONLY-mode failure ('returns an operation_not_permitted error immediately without making any API call'). This materially exceeds what annotations alone convey. No contradiction with the annotations.

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

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

Purpose is front-loaded in the first sentence, followed by one distinct fact per sentence: partial update, immediacy, id sourcing, supported fields, return type, mode gating. The field enumeration is partly redundant with the schema but earns its place as a single-summary of update behavior.

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?

With no output schema present, the description closes the return-value gap by stating 'Returns the updated ShortUrlDTO.' It also covers the READ_ONLY failure path, destructive semantics, and per-field change behavior for a 7-parameter mutation with nested objects — little is left for the agent to infer.

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 every parameter is already documented with behavior ('pass null to remove an existing expiration', 'replaces — not merges — the existing tags'). The description repeats these same semantics rather than adding new meaning, which is the baseline-3 case 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?

States a specific verb and resource: 'Update an existing short URL's configuration.' The scoped field list ('title, expiresAt, isActive, tags, metadata, longUrl') plus the sequencing note 'Use after nevent_list_short_urls' clearly distinguishes it from the create/get siblings (nevent_create_short_url, nevent_get_short_url). No ambiguity remains about what this tool does.

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

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

Explicitly tells the agent when to call it: 'Use after nevent_list_short_urls to get the id.' The WRITE-operation / READ_ONLY-mode warnings also tell the agent when the call will fail. It never names an explicit exclusion (e.g., 'use nevent_create_short_url to create instead'), but for a single-purpose mutation the sequencing guidance supplies enough 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?

The annotations already flag destructiveHint=true, and the description adds useful behavioral context beyond that: updating a template does NOT retroactively change already-sent campaigns. This is a meaningful side-effect disclosure and does not contradict the annotations.

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

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

Three concise sentences with zero filler: the main action comes first, followed by a prerequisite, a minimum-requirement constraint, and an important caveat. Each sentence carries useful information.

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

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

For a mutation tool with no output schema, the description provides the essential invocation context: the target template, the precondition to inspect first, the minimum update requirement, and the key side-effect limitation. It lacks return-value detail, but all parameter semantics are already fully covered by the schema.

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 coverage is 100%, so the schema already documents all six parameters; the description adds an 'at least one of name, content, or tags' constraint. However, this constraint is not enforced in the schema and its wording omits the format parameter, which is a minor semantic gap.

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

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

The description clearly states a specific verb and resource: 'Update an existing email template,' and enumerates the mutable dimensions (name, MJML/HTML content, tags). It does not explicitly differentiate from sibling nevent_rename_template for name-only updates, so it falls short of a 5.

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 gives clear usage context by instructing the agent to call nevent_get_template first to inspect the current version, and states that at least one of name, content, or tags must be provided. It does not explicitly mention when not to use this tool versus alternatives like nevent_create_template or nevent_rename_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?

Beyond the annotations (readOnlyHint: false, destructiveHint: false), the description discloses accepted input formats (data URL vs. raw base64), the 5 MB decoded size limit, the return value type (CloudFront CDN URL), and how that URL is intended to be used. This gives the agent a clear behavioral model of the 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 compact and front-loaded with the core purpose and output, followed by input format constraints, size limit, and downstream usage. Every sentence adds useful information; there is no filler or redundancy.

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

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

Even without an output schema, the description explains the return value (destinationUrl), its format, and how to use it. It also covers the two accepted input forms, size limit, and the relationship to template editing tools, making the tool fully actionable for an agent.

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

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

Schema description coverage is 100%, and the schema already documents source, mimeType, and imageName with their conditions and constraints. The tool description adds limited new parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Upload an image to the Nevent media library and get a CDN URL.' This clearly distinguishes the tool from siblings like nevent_list_images or nevent_delete_image, and the output is concretely identified as a CloudFront destinationUrl.

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 gives a clear workflow: upload the image, then use the returned destinationUrl in nevent_update_template or nevent_create_template HTML. It does not explicitly name alternatives or exclusions, but it does specify when and why this tool should be used, which is strong contextual guidance.

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