Fine Structure

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

Without annotations, the description discloses that the tool returns DNS verification and routing records, indicating a mutation side effect. However, it does not detail whether the operation is reversible, idempotent, or if it overwrites existing domains without confirmation.

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 long with no extraneous information. The first sentence front-loads the core purpose, and the second adds critical behavioral output information.

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

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

Given the tool's simplicity (2 required parameters, no output schema), the description adequately covers purpose and behavior. However, it could mention common error states or prerequisites like domain ownership verification, but is sufficient for basic 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 input schema already provides clear descriptions for both parameters (app_id and domain). The description adds no additional semantics beyond what the schema states, so it meets the baseline for full schema coverage.

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

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

The description clearly states the tool attaches or replaces a custom domain for an app, distinguishing it from sibling tools like remove_custom_domain, check_domain_verification, and set_primary_domain by focusing on the initial setup/replacement of the domain itself.

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

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

No explicit guidance on when to use this tool versus alternatives like check_domain_verification or set_primary_domain is provided. The description implies it is part of the custom-domain flow, but does not specify prerequisites or exclusions, leaving room for agent misinterpretation.

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

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

With no annotations, the description adds key behavioral context (no live modification until apply_change_set). However, it lacks details on error handling, limits, or overlap with existing staged changes.

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 concise sentences with front-loaded purpose. Every word is informative, no wasted 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 6 parameters and no output schema, the description covers the core purpose and a key behavioral trait. However, it omits lifecycle context (e.g., need for existing change set) and return behavior, making it adequate but not 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 83%, and the description adds no extra information beyond what the schema provides for parameters. 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 clearly states it stages one file upsert or delete within a change set, distinguishing it from siblings like write_app_file (direct live modification) and apply_change_set (applies all staged changes).

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

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

The description implies usage for staging changes before applying, and explicitly notes it does not modify the live app until apply_change_set. However, it does not provide explicit when-not-to-use guidance or mention alternatives for direct file writes.

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 provided, so description carries full burden. It mentions 'Agency mode only' and the login requirement for ownership transfer. It does not disclose potential side effects, error cases, or what happens to the app afterward. Adequate but not detailed.

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, no redundant information, front-loaded with key constraints. Every part 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?

The description covers the core behavior and constraints but lacks information about what the tool returns (no output schema). Given the moderate complexity (6 params), it is mostly 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 coverage is 100% (all 6 parameters documented in schema). The description adds no additional meaning or constraints beyond what the schema provides, so it is at baseline 3.

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 (create client claim link), context (agency mode only, existing app owned by agent), and a key behavior (client must log in with invited email). It distinguishes from sibling tools like agency_create_client and agency_get_claim_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 specifies the usage context 'Agency mode only.' It implicitly indicates when to use (to transfer ownership). However, it doesn't explicitly say when not to use or mention alternatives, though the sibling list provides 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?

Without annotations, the description adds moderate behavioral transparency by stating that the tool does not create a verified user account and does not transfer ownership. However, it omits other behavioral traits such as required permissions, side effects, or idempotency guarantees.

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

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

The description is extremely concise with two short sentences, front-loading the key constraint ('Agency mode only'). 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?

Despite having only 3 parameters and no output schema, the description lacks details about what 'update' entails, the lookup key for updates (presumably client_email), error conditions, and the return value. This leaves significant gaps for an agent to interpret 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%, and the description does not add extra meaning beyond the parameter descriptions already in the schema. The baseline of 3 is appropriate as the description provides no additional semantic value.

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

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

The description clearly states it creates or updates a client record in agency mode, and explicitly distinguishes it from creating a verified user account. However, it does not differentiate from sibling tools like agency_create_claim_link or agency_create_client_app.

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 specifies 'Agency mode only' as a usage condition, but provides no guidance on when to use this tool versus alternatives (e.g., agency_create_claim_link), nor any exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavior: ownership transfers only when the invited client logs in with the same email and accepts the claim link. However, it lacks details on return value, potential errors, or auth requirements beyond 'Agency mode only'.

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, front-loaded with the core action and mode, followed by a concise explanation of the ownership transfer. No redundant or extraneous information.

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

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

Given the complexity of an agency workflow with 8 parameters and no output schema, the description explains the claim link process but omits what the tool returns (e.g., claim link URL or app ID). It is sufficient but not exhaustive.

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

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

The input schema provides descriptions for all 8 parameters (100% coverage). The description adds overarching context about claim creation and ownership transfer, but does not elaborate on specific parameter meanings beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Agency mode only. Create a new app owned by the agent, start generation, and create a claim link for the client.' It specifies the verb (create), resource (app), and distinguishes from siblings like 'agency_create_claim_link' and 'agency_create_client'.

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 indicates 'Agency mode only,' which guides when to use it. It explains the ownership transfer process, but does not explicitly contrast with alternatives like 'create_app' or provide 'when not to use' scenarios. Overall, the context is clear enough for an agent.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool does not expose the raw claim token, which is a safety-related behavioral trait. However, it omits other important aspects such as whether the tool is read-only, what its output looks like, or potential errors. The description adds some value but lacks completeness.

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 exceptionally concise at 14 words, with a front-loaded constraint ('Agency mode only') followed by the clear action. Every sentence adds distinct value without redundancy. This is a model of 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?

For a simple tool with one parameter and no output schema, the description captures the core purpose and a key behavioral trait (hiding the raw token). However, it fails to describe what the output contains (e.g., status value, success indicator) or how the tool fits into a workflow. This leaves some ambiguity for the agent.

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

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

Schema coverage is 100%, so the parameter is fully documented in the schema. The description does not add any extra meaning beyond the schema's own description of 'handoff_id'. It does not explain the parameter's format, constraints, or relationship to other tools.

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

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

The description clearly states the tool's purpose: 'Inspect one handoff status' with the qualifier 'Agency mode only'. It distinguishes itself from sibling tools like agency_create_claim_link by focusing on inspection rather than creation, and adds context about not exposing the raw token. However, it does not explicitly name differentiating siblings.

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

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

The description provides no guidance on when to use this tool versus alternatives. It lacks conditions for usage, exclusions, or references to related tools such as agency_list_clients. The only instruction is 'Agency mode only', which limits scope but does not help in decision-making.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read operation but does not explicitly state that it is non-destructive or safe, nor does it describe permissions, rate limits, or side effects.

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

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

The description is two sentences, front-loading the action and scope. Every sentence adds value 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?

The description covers the purpose and a prerequisite, but lacks details about the return format or behavior. Given there is no output schema, more context would be helpful 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 parameter description in the schema is identical to what the tool description adds. No additional meaning beyond the schema is provided, 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 clearly states the action ('list') and the resource ('client records and app handoff status'). It also specifies the scope ('Agency mode only'). However, it does not explicitly differentiate from other list tools, though no conflicting siblings exist.

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 only mentions 'Agency mode only' as a prerequisite. There is no guidance on when to use this tool versus alternatives, nor when not to use 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?

Without annotations, the description discloses important behaviors: it creates a Saved Version before applying and blocks on validation errors unless force=true. This provides useful behavioral context beyond the schema, though it omits details like whether the change set is consumed or permissions required.

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 concise sentences deliver the core purpose and key behavioral details with no wasted words. The first sentence front-loads the primary action.

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 description covers the main behavioral aspects and side effects (creating a Saved Version, error handling). However, it does not mention return values or status on success, which would be helpful given no output schema. Overall sufficient for an apply operation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning to the parameters (force, app_id, change_set_id) 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 clearly states the action ('Apply a staged change set') and the resource ('change set'), differentiating it from sibling tools like create_change_set and discard_change_set. The additional details about creating a Saved Version and blocking on validation errors add context, but it does not explicitly distinguish from validate_change_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?

No explicit guidance on when to use this tool versus alternatives like validate_change_set or publish_app. The description hints that it is used after staging changes, but lacks clear context or exclusions.

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

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

The description indicates a side effect ('save the latest status') but does not disclose whether the operation is destructive, requires authentication, or has rate limits. No annotations exist to supplement this.

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 sentence that is concise and front-loaded with the core action. No unnecessary 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?

Missing description of return value (no output schema) and no guidance on when to use over similar sibling tools. Incomplete for a tool with two parameters and a save action.

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% with both parameters described adequately. The description does not add extra meaning beyond what the schema provides, so 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 action ('check verification and SSL status' and 'save') and the resource ('custom domain'), distinguishing it from read-only siblings like get_domain_verification.

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 on when to use this tool versus alternatives such as get_domain_verification or get_domain_ssl_status. No prerequisites or when-not-to-use mentioned.

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 provided, so description must disclose behavior. It states it returns diffs, but does not confirm read-only nature, mention pagination or truncation, or explain max_diff_chars behavior. The compaction of diffs is mentioned but not elaborated.

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?

Single sentence with zero filler. Front-loaded with the core action and output type. 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 diff tool with 3 parameters and no output schema, the description covers the basic purpose and output. However, it omits read-only hint, return format details, and explanation of max_diff_chars. Adequate but has gaps.

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

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

Schema description coverage is 67% (2 of 3 params described). The description adds no extra meaning beyond the schema for app_id and snapshot_id. The max_diff_chars parameter is not explained in the description, though its name and default hint at truncation. With high coverage, baseline is 3.

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?

Title and description clearly identify the verb 'compare', the resources 'current app files' and 'Saved Version', and the output 'compact per-file diffs'. This distinguishes it from siblings like 'compare_saved_versions' which compares two saved versions.

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

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

The description implies usage for viewing differences between current files and a specific saved version, but does not provide explicit guidance on when to use it versus alternatives like 'compare_saved_versions' or 'restore_file_from_version'. No when-not-to-use or prerequisite info.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It states the outputs but does not disclose side effects, permissions required, rate limits, or whether it's a read-only operation. The description is insufficient for a tool with no annotations.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded with the action and immediately specifies the output. Perfectly concise.

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 description explains what the tool returns but does not mention the behavior of the 'max_diff_chars' parameter, any limitations on snapshot IDs, or the expected format of diffs. Given the moderate complexity and lack of output schema, more detail would improve completeness.

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

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

The input schema has 75% description coverage, meaning three out of four parameters have descriptions. The tool description does not add any extra meaning beyond what is already in the schema. Since coverage is high, baseline is 3, and no added value, score is 3.

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 'compare', the resource 'Saved Versions', and specifies the output: per-file additions, removals, modifications, and compact diffs. This distinguishes it from sibling tools like 'compare_current_to_version' and 'restore_saved_version'.

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 (to compare two saved versions) but does not explicitly exclude other tools or provide context on when not to use. No alternatives or prerequisites are mentioned, so guidance is minimal.

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 provided, so description carries full burden. It lists configurable elements but fails to disclose behavioral traits: whether changes overwrite existing redirects, take effect immediately, require domain verification, or have destructive side effects. Does not describe response or confirm action.

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

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

Single sentence with clear structure: verb, resource, list of configurable elements. No unnecessary words. Could benefit from brief additional context but remains efficient.

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

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

With 4 parameters, no output schema, and no annotations, the description is insufficient. Missing prerequisites (domain must be added and verified), behavior on repeated calls, and any error conditions. A configuration tool needs more context 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 coverage is 100%, baseline 3. Description mentions parameters (primary_domain, redirect_www, force_https) but adds no additional meaning beyond their names and defaults. Does not explain semantics like effect of toggling redirect_www or force_https.

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 clearly states verb 'Configure' and resource 'custom-domain redirect policy', listing specific aspects: primary domain, www/root redirect, HTTPS enforcement. It distinguishes from siblings like add_custom_domain and set_primary_domain by focusing on redirect policy.

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?

Implied usage context: to set redirect policies for custom domains. However, no explicit guidance on when to use this tool versus alternatives (e.g., add_custom_domain or set_primary_domain), no when-not conditions, and no mention of prerequisites.

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 provided, so the description carries full behavioral disclosure burden. It states it stores safe non-secret metadata, but does not reveal whether it creates/updates, idempotency, permissions, rate limits, or side effects. The input schema adds some context about 'safe metadata' but overall behavioral traits are under-specified.

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 concise sentences, front-loaded with purpose and sibling differentiation. Every word adds value 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?

Given the tool has 4 parameters including a nested object and no output schema or annotations, the description is too minimal. It lacks information on return value, update behavior, error conditions, and prerequisites (e.g., app existence). While schema descriptions help, the description alone does not provide sufficient context for correct 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?

Schema description coverage is 100%, so baseline is 3. The description reinforces the non-secret nature of config but does not add new parameter-specific details beyond what the schema already provides. The schema descriptions themselves are clear enough.

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 stores safe non-secret integration metadata for an app, with a specific verb 'store' and resource. It also distinguishes from the sibling tool set_secret by explicitly mentioning where to put secrets.

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 this tool for non-secret integration metadata and set_secret for API keys/tokens. However, it does not cover other potential alternatives like list_integrations or update scenarios, but the given guidance is sufficient for the main decision.

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

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

With no annotations, the description must carry the full burden. It discloses that a Saved Version is created before the change, which is a key behavioral trait. It does not mention potential errors, permission requirements, or rate limits. The description provides adequate but not comprehensive transparency.

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

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

The description is three sentences with no redundancy. It front-loads the purpose, follows with a usage hint, and ends with a behavioral note. Every sentence earns its place, making it concise and efficient.

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

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

For a create tool with no output schema, the description covers purpose, preconditions, and a side effect. It lacks details about the return value or error conditions, but given the tool's simplicity and the high schema coverage, it is fairly complete. Sibling differentiation is adequate.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters. The description does not add details beyond the schema. The baseline score of 3 applies because the schema does the heavy lifting, and the description adds marginal value for parameters.

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

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

The description clearly states the action 'Create' and the resource 'native Fine Structure A/B test'. It distinguishes from siblings like update_ab_test and delete_ab_test by specifying creation between existing app pages. The mention of 'use update_app first' adds further clarity.

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

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

The description gives a clear precondition: use update_app if a variant page is missing. This helps the agent decide when to use this tool. However, it does not explicitly state when not to use it or list alternative tools, but the context is sufficient for typical use.

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

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

With no annotations provided, the description bears full responsibility. It transparently discloses that the tool is asynchronous (returns a job_id), that the AI generates a full app (pages, components, etc.), and that the app becomes ready upon job completion. No destructive actions or rate limits are mentioned, but the core behavior is well covered.

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 composed of three concise sentences. The first sentence states the core purpose, the second elaborates on what is generated, and the third provides post-call instructions. No extraneous information is included.

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 adequately explains the return value (job_id) and the need for polling. It covers input (name, prompt), process (AI generation), and follow-up (poll get_job_status). It does not specify error conditions or limits, but for a straightforward creation tool with three parameters, it 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 coverage is 100%, so baseline is 3. The description does not add significant semantic value beyond the schema's brief descriptions (e.g., 'Name for the app (1-100 chars)'). The mention of 'natural language prompt' loosely relates to the prompt parameter, but there is no deeper explanation of parameter usage.

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

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

The description clearly states 'Create a new application from a natural language prompt', specifying a concrete verb and resource. It further details that the AI generates a complete web app, distinguishing it from sibling tools like create_ab_test or update_app.

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 the agent to poll get_job_status after calling, providing clear follow-up guidance. While it doesn't mention when not to use this tool or list alternatives, the context is sufficient given the presence of sibling tools like write_app_file or update_app.

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?

Without annotations, the description carries the burden. It mentions 'staged' and 'atomically apply', indicating it is a non-destructive creation. However, it does not clarify that adding files is done separately (via add_file_change), which could confuse agents about the tool's exact behavior.

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

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

The description is two sentences (17 words), front-loads the purpose, and contains no redundant information. 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 description provides some workflow context but lacks details on prerequisites (e.g., must app_id exist?), error states, or what happens with multiple change sets. Given simple parameters and no output schema, it is moderately complete but could be improved.

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 two simple parameters (label and app_id). The description adds no additional meaning beyond the schema, meeting the baseline of 3.

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 'Create a staged file change set' as the primary action, with a specific verb and resource. It also distinguishes from siblings like apply_change_set and add_file_change by outlining the workflow context.

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

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

The description implies the tool is the first step in a multi-step process (add, validate, apply), providing clear context for when to use it. However, it does not explicitly state alternatives or exclusions, but the context is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that no records are written until the owner approves in Studio chat, which is a critical non-destructive behavior. This goes beyond basic write semantics and helps the agent understand the approval workflow.

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 stating the action and the key constraint. Every word 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?

Given the tool has five parameters, full schema coverage, and no output schema, the description is concise but sufficiently complete for an agent to select and invoke it correctly. It explains the core behavioral nuance (approval required). It could add a bit more about the process after approval or relationship to sibling tools, but overall it covers the essentials.

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 with descriptions for all five parameters, so the baseline is 3. The description adds the 'proposal' context which informs how to set parameters (e.g., records are proposed, not final), but it does not add per-parameter syntax or format details beyond what the schema already gives.

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 'Propose creating/inserting' and identifies the resource 'records in one app entity'. This clearly differentiates from sibling tools like update_entity_records (updating) and seed_entity (seeding), and the 'one app entity' scoping adds precision.

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: this tool is for proposing record creation that requires explicit owner approval. It implies use when you want to create records but must not write directly. However, it does not explicitly name alternatives or state when not to use it, so it lacks 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?

With no annotations, the description carries the burden. It discloses the version creation side effect, which is beyond the schema. However, it does not clarify destructive potential (overwrite) or error conditions, leaving gaps for an agent.

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 very short (two sentences) and to the point. It avoids redundancy but could include more useful information without becoming verbose.

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 7 parameters with nested objects and no output schema, the description is incomplete. It lacks explanation of parameter purposes, return value (none), error scenarios, and does not leverage output schema since none exists. An agent would need additional context.

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

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

Schema description coverage is only 43%, and the description adds no parameter details. Parameters like indexes, metadata, overwrite, and relationships are not explained beyond the schema. The description does not compensate for the low coverage.

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

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

The description clearly states the verb 'Create', the resource 'entity schema file', the specific path pattern 'entities/<Entity>.json', and a notable side effect 'Creates a Saved Version before writing'. It distinguishes from sibling tools like update_entity_schema and seed_entity.

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 on when to use this tool versus alternatives (e.g., update_entity_schema, seed_entity). No prerequisites are mentioned (e.g., app must exist). The overwrite parameter exists but its effect is not explained.

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

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

With no annotations, the description carries full burden. It discloses a key side effect: 'Creates a Saved Version before the change.' This adds value beyond a simple 'delete' statement, though it doesn't detail other behaviors like idempotency or permission requirements.

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

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

The description is extremely concise with two sentences, no unnecessary words, and front-loads the key action and side effect.

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 are only two parameters, no output schema, and a sibling list that includes create/update, the description adequately covers the purpose and a notable side effect. It could mention permanence, 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 input schema has 100% description coverage, providing baseline clarity. The tool description does not add any additional meaning to the parameters (app_id, test_id) beyond what the schema already states.

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

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

The description clearly states the action ('Delete a native A/B test from an app') and distinguishes it from other test-related tools like create_ab_test or update_ab_test by specifying it is a deletion operation.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for deletion but lacks context such as prerequisites or when not to use 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?

With no annotations, the description carries the full burden and does well by explicitly stating that it freezes matched IDs and returns pending approval, with zero records deleted until approval. This reveals the non-destructive, proposal-like behavior, which is critical for an agent to understand. It could further mention post-approval outcomes, but the core behavioral trait is covered.

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 wasted words. It front-loads the core purpose and includes the key caveat about pending approval. Every phrase 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 six parameters, no output schema, and no annotations, the description sufficiently frames the tool's behavior and purpose. It explains the pending-approval flow and mentions safety checks implicitly through 'exact-match', but it does not describe the approval process details or what happens after approval. Still, for a proposal-style tool, this is adequate and complete enough for an agent 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?

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds semantic value by grouping the selection methods into 'by ID or exact-match filters', which maps to record_ids and filters, and by mentioning the exact-match requirement. This goes slightly beyond 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 tool proposes deleting records by exact ID or exact-match filters, which is a specific verb (propose deleting) plus resource (records). It distinguishes itself from siblings like update_entity_records and seed_entity by framing it as a deletion proposal rather than a direct mutation.

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 explains the tool returns a pending approval and that nothing is deleted until an owner approves, giving clear context for when it should be used. It does not explicitly list alternatives or exclusions, but the behavioral note makes the use case and approval requirement 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?

Without annotations, the description must declare behavioral traits. It only states the action as 'delete', implying mutation but omits critical details like irreversibility, auth requirements, or behavior when the key doesn't exist. This leaves the agent uninformed 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?

The description is a single 6-word sentence, extremely concise and front-loaded. While it efficiently conveys the core action, it sacrifices potentially important details, earning a slight deduction for being overly minimal.

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 and the need for behavioral context in a mutation tool, the description is insufficient. It does not explain the return value, error handling (e.g., missing key), or any confirmation of deletion, leaving the agent without complete usage 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 description's mention of 'by key' adds minimal value beyond the schema's 'Secret key name'. The 'app_id' parameter is not mentioned in the description, though it's required. The description does not enrich parameter understanding.

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

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

The description uses a specific verb 'Delete' and resource 'app secret', clearly indicating the action. The phrase 'by key' further specifies the selection mechanism, making it distinct from siblings like 'set_secret' or 'list_secret_keys'.

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

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

No guidance is provided on when to use this tool versus alternatives, such as 'set_secret' for updating or 'list_secret_keys' for inspection. The description lacks context for decision-making or prerequisites.

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?

Without annotations, the description reveals that the tool does not alter app files, which is a key non-destructive trait. However, it does not specify whether the discard is reversible or what exactly happens to the change set 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?

The description is a single, efficient sentence that conveys the action and its key constraint without any unnecessary 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?

Given the tool's simplicity and 2 required parameters, the description is largely complete. It could mention the outcome (e.g., success/failure) or whether the action is reversible, but the core information 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?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional parameter-level meaning beyond what the schema provides, meriting the baseline score of 3.

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 specifies the verb 'Discard' and the resource 'pending staged change set', explicitly stating it does not change app files. This distinguishes it from siblings like apply_change_set and create_change_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 mention of 'pending staged change set' implies the change set must be in a staged state, but there is no explicit guidance on when to use this tool versus alternatives like apply_change_set or create_change_set.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Configure isolated Email Marketing settings' without revealing side effects (e.g., whether it overwrites existing settings, requires a specific app state, or is idempotent). This is insufficient for a mutation tool.

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

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

The description is a single sentence with no wasted words. However, it could be structured better (e.g., bullet points for key settings) to improve readability. It is concise but slightly under-specified.

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

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is too sparse. It does not explain what 'isolated' means, what settings are configured, or any prerequisites. The context from sibling tools suggests this is important but the description leaves significant gaps.

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

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

With 8 parameters and only 50% schema description coverage, the description adds no parameter information. It fails to compensate for the missing schema descriptions, leaving half of the parameters (reply_to, is_enabled, sender_name, sender_email) entirely undocumented in both schema and description.

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 (configure) and the resource (Email Marketing settings for a generated app). It distinguishes this tool from siblings by specifying 'isolated' and 'for a generated app', which aligns with the many other email marketing tools focused on broadcasts, sequences, etc.

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 only mentions that the tool 'can be used by Studio/chat agents', but provides no guidance on when to use this tool versus alternatives like 'email_marketing_configure_sender' or other email marketing tools. No when-not or prerequisite information is included.

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

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

With no annotations provided, the description carries the full burden. It indicates a read-only operation by using 'Read,' but lacks details on side effects, authentication requirements, rate limits, or data volume. The description is adequate but not comprehensive.

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 single, clear sentence that immediately states the action and resource. It is concise and contains no unnecessary words, though it could be slightly restructured for easier parsing of the listed items.

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 simplicity of the tool (two string parameters, no output schema), the description adequately explains the inputs and hints at the output content. However, since there is no output schema, the description could more explicitly state the return format or structure.

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

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

The schema already describes both parameters ('The app ID' and 'Contact id or email address') with 100% coverage. The description adds no additional meaning or constraints, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Read') and the resource ('contact profile'), and specifies the scope including email delivery, tracking, app-event, workflow, suppression, and unsubscribe timeline. This distinguishes it from sibling tools that perform write operations or other functionalities.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusion criteria, which is a significant gap given the many 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?

No annotations are provided, so the description should fully disclose behavioral traits. It mentions creating a broadcast with optional scheduling, but omits side effects, authorization needs, rate limits, or return behavior, which is insufficient for a complex tool.

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

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

The description is concise (one sentence) but lacks structured presentation of options or parameters. It is front-loaded with the core action, but could be more organized for clarity.

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

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

Given the complexity of 8 parameters, nested objects, no output schema, and no annotations, the description is incomplete. Missing details on filters, body_html, timezone, and return values leave significant gaps.

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

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

With only 25% schema description coverage, the description adds minimal meaning beyond the schema. It touches on scheduling (send_now, scheduled_at) but does not explain other parameters like name, timezone, body_html, or filters.

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 it creates an app-scoped broadcast, specifying the scope and optional scheduling. However, it does not explicitly differentiate from the sibling tool 'email_marketing_create_broadcast'.

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

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

The description implies usage for app-specific broadcasts and scheduling options, but lacks explicit when-to-use or when-not-to-use guidance, especially relative to similar 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?

No annotations provided, so description carries full burden. Describes the basic action but omits side effects, permissions, mutability, or rate limits. Insufficient for safe agent use.

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?

Single sentence, no redundancy, front-loaded with key action. Every word 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?

Given 8 parameters (4 required, nested objects) and no output schema, description is too sparse. Leaves out return values, default behaviors, and parameter relationships. Incomplete 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 coverage is 50% (4 of 8 params have descriptions). Description adds only event examples, providing little additional meaning. Fails to explain complex parameters like filters or entity_name.

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 clearly states the action (create), resource (app-scoped email rule), and trigger condition (when an app event is recorded), with specific examples. This distinguishes it from sibling tools like broadcasts or sequences.

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

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

No explicit guidance on when to use this tool versus alternatives. Does not mention exclusions or prerequisites. Agent must infer from context.

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

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

No annotations provided, so the description carries full burden. It mentions 'saved audience segment' implying persistence, but lacks details on side effects, permissions, rate limits, or whether the creation is synchronous. Minimal behavioral 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?

Single sentence with no redundant words. Clearly front-loaded with action and resource, then specifics (filters). Every word contributes to understanding.

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

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

Given the complexity (nested object, 4 params, no output schema), the description is too brief. It doesn't mention the return value, error scenarios, or what 'app-scoped' means for the required app_id. A creation tool should clarify that the segment is persistent and provide success confirmation.

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 50% (two of four parameters have descriptions). The description adds value for 'filters' by specifying 'field, tag, and behavior filters', which goes beyond the schema's generic description. However, 'name' and 'sample_limit' are not elaborated, and the description doesn't explain their roles.

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 'Create' and the resource 'app-scoped saved audience segment', which is distinct from sibling tools like create_broadcast or create_sequence. The mention of filters (field, tag, behavior) adds specificity.

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 on when to use this tool versus alternatives (e.g., email_marketing_app_create_broadcast). No context about prerequisites or typical scenarios, leaving the agent to infer from the name alone.

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

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

No annotations exist, and the description does not disclose side effects, permissions needed, rate limits, or any destructive actions. It merely states what it creates without behavioral context.

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

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

A single sentence is very concise, but it lacks structure. It earns its place but could be more informative without adding length.

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 7 parameters (2 required), nested objects, and no output schema, the description is insufficient. It does not explain relationships between schedule_mode and start_at, or how to structure steps, making it incomplete for complex 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?

Schema coverage is 57%, and the description adds context about steps supporting subject, body_html, scheduled_at, day_offset, or gap_days. However, other params like app_id, filters, timezone are not elaborated beyond schema.

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

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

The description clearly states the verb 'Create', the resource 'app-scoped email sequence', and the modes (fixed dates or day offsets). It distinguishes from sibling 'email_marketing_create_sequence' which likely lacks app scoping.

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 on when to use this tool versus alternatives like 'email_marketing_create_broadcast' or 'email_marketing_create_sequence'. No prerequisites or exclusions provided.

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 provided, so description bears full burden. It only states the creation action without disclosing side effects (e.g., whether the workflow starts immediately, auth requirements, or rate limits). Does not mention if it saves or activates.

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?

Single sentence with no wasted words. Front-loaded with verb and object, efficient.

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

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

Despite complexity (7 parameters, nested objects, 2 required), the description is minimal. No output schema, no explanation of return values or behavior after creation. For a creation tool with many configuration options, more context is needed.

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 high (71%), with descriptions for most parameters. The tool description repeats the step type values already in the schema description, adding no new meaning. 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 'Create' and identifies the resource 'automation workflow' with scope 'app-scoped'. It lists supported step types (email, wait, condition, split, goal), which helps differentiate from sibling tools like 'create_broadcast' or 'create_sequence'.

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 on when to use this tool vs alternatives (e.g., when to use 'create_workflow' versus 'create_sequence'). Lacks prerequisites, context, or exclusions.

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

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

No annotations exist, and the description only asserts a read operation without disclosing permissions, rate limits, or potential side effects. More behavioral context is needed for a tool with no annotation 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?

A single, focused sentence that conveys the tool's purpose efficiently without unnecessary words 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?

Given the tool has only one parameter, no output schema, and no nested objects, the description adequately lists the types of data returned. However, it lacks details on output format, filtering, or date ranges, which would improve completeness.

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

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

Schema coverage is 100% for the sole parameter app_id, with a clear description in the schema. The tool description does not add additional parameter semantics beyond what is already in the schema.

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

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

The description clearly states it reads deliverability metrics including provider readiness, bounce/complaint rates, suppression reasons, and risk events. This distinguishes it from sibling tools like email_marketing_app_status (general status) or email_marketing_app_report (wider reporting).

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

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

The description implies usage for checking deliverability health but does not explicitly state when to use versus alternatives or when not to use. No exclusions or context are provided.

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 provided, so description carries the burden. It mentions locks, retries, and suppression checks, indicating concurrency and safety behavior, but fails to disclose whether the tool is read-only or mutating, or any failure modes.

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?

Single sentence with no filler. While efficient, the dense technical jargon ('locks, retries, suppression checks') could be clearer but does not detract from 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?

With no annotations and no output schema, the description lacks details on return values, side effects, and invocation outcomes. It omits whether the tool returns a status or job ID, leaving the agent uncertain about what to expect.

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 50% (only 'app_id' has a description). The tool description adds no parameter information; it does not explain 'app_id' or 'max_jobs' beyond what the schema provides, failing to compensate for the low coverage.

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

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

The description clearly states it processes 'due app-scoped automation workflow runs and email queue jobs' with specific mechanisms. The verb 'process' and resource identification are clear, and there is no directly competing sibling 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?

No guidance on when to use this tool versus alternatives like 'email_marketing_app_queue_status' or other processing tools. Absence of when-not-to-use or prerequisite conditions limits actionable clarity.

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 indicates a read-only operation ('Inspect') and app-scoping, which is the main behavioral trait. No annotations are provided, so the description bears full burden. It does not mention potential side effects, performance, or error handling, but is minimally adequate for a simple query 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?

Single sentence that is front-loaded with the verb and object. No wasted words; efficient for conveying core purpose.

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

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

For a simple query tool with no output schema, the description is minimal but covers the essential purpose. It does not mention pagination or behavior with large queues, but given the simplicity, it is marginally 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?

Description adds no parameter meaning beyond the input schema. Schema covers 67% of parameters (app_id and status have descriptions), but limit lacks both schema description and any mention in tool description. The description does not compensate for the missing schema description.

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 clearly states the tool inspects app-scoped email marketing queue jobs and per-status counts. It uses a specific verb-resource combination and distinguishes from sibling tools like email_marketing_app_process_queue and email_marketing_app_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?

No guidance on when to use this tool vs alternatives such as email_marketing_app_status or email_marketing_app_report. Missing when-not-to-use or context for exclusion.

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

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

With no annotations, the description only says 'record' and 'send', but does not disclose any side effects, permission requirements, or what 'matching triggers' entails. This is minimal for a mutation tool.

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

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

The description is very short (one sentence), but it under-specifies the tool for effective use. It is concise but at the expense of completeness.

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 8 parameters, nested objects, and no output schema, the one-sentence description is insufficient for an agent to understand how to correctly invoke the tool or interpret its 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?

The description adds no meaning to the parameters beyond their schema names. With 50% schema coverage, the description could have clarified parameter usage, especially for nested objects like record and properties.

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 records an event and sends matching triggers, distinguishing it from sibling tools that create triggers or configure email marketing. However, it does not explicitly differentiate from similar tools like email_marketing_app_create_event_trigger.

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 on when to use this tool versus alternatives like creating event triggers or triggering variables. The description lacks context about prerequisites or scenarios.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It only states 'Read', implying no side effects, but does not mention data freshness, pagination, rate limits, or what exactly 'recent tracking events' entails. This leaves significant ambiguity for agent usage.

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

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

The description is a single concise sentence, but it sacrifices essential information for brevity. While it has no fluff, it is not sufficiently informative to earn a higher score.

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

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

The tool has 4 parameters, no output schema, and many siblings. The description is too brief; it omits parameter meanings, output structure, and usage context. This leaves the agent with an incomplete understanding of the tool's capabilities.

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 only 25% (only app_id is described). The description adds no parameter details; it does not explain how limit, segment_limit, or include_events affect the report. With such low coverage, the description should compensate but fails to do so.

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 reads app-scoped email marketing reporting, listing specific metrics like delivery counts, open/click rates, and tracking events. It distinguishes from sibling tools by focusing on aggregated reporting rather than status or configuration, though it could be more explicit about its unique 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?

No guidance is provided on when to use this tool versus alternatives. Given many sibling email marketing tools (e.g., email_marketing_app_status, email_marketing_app_deliverability), the description should indicate that this is for detailed reporting and not for real-time status or other operations.

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

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

Without annotations, the description carries full burden. It indicates 'inspect' implying no side effects, but does not disclose any behavioral traits like authentication, rate limits, or response size. Important details are missing for safe invocation.

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 single, front-loaded sentence that efficiently conveys the tool's purpose without extraneous detail. It earns its place, though could slightly expand on parameter effects.

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 or annotations, the description provides a reasonable overview of what is inspected. However, it lacks specifics on format, pagination, or error states, which are needed for a complete understanding.

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

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

Schema coverage is 50%: app_id is described but include_logs lacks description. The tool description does not add meaning beyond listing components; it omits explaining how parameters affect results, leaving agents to infer behavior.

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 'inspects' Email Marketing data for one app, listing specific components (settings, contacts, campaigns, event triggers, recent events). This distinguishes it from sibling tools that modify or perform other actions, though it could more explicitly contrast with similar read tools like email_marketing_app_deliverability.

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 read-only use case but provides no guidance on when to use this tool versus alternatives, such as when to use email_marketing_app_report for specific metrics. No exclusions or context for selection are given.

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 full burden. It mentions the tool suppresses contact emails after certain events but does not disclose behavioral traits such as whether the action is reversible, destructive, or requires specific permissions. The term 'suppress' implies state modification but with no consequences described.

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 single sentence of 16 words, front-loaded with the verb and purpose. It is concise and avoids redundancy, though it could include more detail without becoming verbose.

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 5 parameters (including a nested object), no output schema, and low parameter coverage, the description is insufficient. It does not explain the impact of suppression, required input details, or return behavior, leaving gaps for the agent.

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

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

Schema description coverage is only 20% (only app_id described). The description does not explain the parameters (email, reason, source, metadata) beyond the overall purpose. Given the low coverage, the description should compensate but fails to add meaning to the parameters.

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

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

The description clearly states the tool's purpose: to suppress a contact email in an app after specific events (bounce, complaint, etc.). It distinguishes the tool from siblings like email_marketing_app_contact_profile and email_marketing_app_sync_contacts by specifying the suppression action and context.

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

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

The description implies usage after certain events (bounce, complaint, etc.) but does not explicitly state when to use this tool versus alternatives, nor when not to use it. No exclusions or alternative recommendations are provided.

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 mentions that records without valid email are skipped, but fails to disclose critical behavioral traits such as whether existing contacts are updated or replaced, whether the sync is additive or destructive, or what happens to contacts not present in the entity table. Since no annotations are provided, the description bears full responsibility for transparency.

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

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

The description is very concise (two short sentences) and front-loaded with the main action, but it sacrifices necessary detail. While not verbose, it is under-specified for a tool with five parameters and no annotations, making it only minimally adequate.

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

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

Given the complexity (5 parameters, no output schema, no annotations), the description is severely incomplete. It fails to explain sync semantics, conflict resolution, whether the operation is incremental or full, what data is synced beyond email, or any side effects. This is insufficient 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?

With only 40% schema description coverage, the description does not compensate for the missing parameter semantics. It does not explain the purpose of 'name_field', 'email_field', or 'limit', leaving the agent to infer mapping logic from the tool name. The description should clarify how entity fields map to contact fields.

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 syncs an app entity table into app-scoped Email Marketing contacts, specifying the scope ('app-scoped') and that records without valid email are skipped. This distinguishes it from sibling tools like email_marketing_app_contact_profile (single contact) or email_marketing_app_suppress_contact (suppression).

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., manual contact creation or single contact updates). There are no hints about prerequisites, limitations, or scenarios where other tools might be preferred. The description simply states what it does without 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?

In the absence of annotations, the description discloses that it is admin-only and that the unsubscribe footer remains mandatory. However, it does not detail side effects of configuration changes, permissions beyond admin, or the mutation behavior, leaving some transparency gaps.

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

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

The description is very concise with three short sentences. It places the important prerequisite first and avoids any extraneous information. Every sentence serves a purpose.

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

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

With 7 optional parameters and no output schema, the description is adequate but not complete. It does not clarify what happens when no parameters are provided, nor does it describe the expected response or confirmation of changes. More detail would be beneficial for a configuration 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 baseline is 3. The description adds minimal meaning beyond the schema by grouping 'sender details' and 'module enabled state', but it does not explain parameter syntax or relationships in a way that adds significant 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 the verb 'configure' and clearly identifies the resource: 'global Email Marketing sender details and module enabled state'. It is specific enough to convey the tool's scope, though it does not explicitly differentiate from similar sibling tools like email_marketing_app_configure.

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 only states 'Admin only' as a prerequisite but provides no guidance on when to use this tool versus alternatives such as email_marketing_app_configure, nor does it specify conditions or exclusions.

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

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

No annotations are present, so the description must convey all behavioral traits. It mentions admin-only access and optional scheduling but does not disclose default behavior (e.g., whether the broadcast is created as a draft if not sent immediately) or any side effects. The mutation nature is implied but not explicit.

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 single sentence plus 'Admin only.' It is extremely concise, front-loads the most critical restriction, and contains no wasted words.

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

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

Given the tool's complexity (7 parameters, nested object) and the absence of an output schema or annotations, the description is too brief. It does not explain the return value, error conditions, or how to structure the filters object. Important details like whether the broadcast is created immediately or as a draft are 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%, so the baseline is 3. The description adds limited value beyond the schema by framing the tool as a 'filtered campaign' and mentioning scheduling, but it does not clarify the role of individual parameters like filters or scheduled_at beyond what is in the schema.

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

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

The description clearly states it creates a filtered broadcast campaign for admins, with optional scheduling. It is specific but does not explicitly distinguish from sibling tools like email_marketing_app_create_broadcast or email_marketing_create_sequence.

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

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

The description includes an admin-only restriction, indicating who should use it. However, it does not provide guidance on when not to use it or suggest alternatives, such as for unfiltered broadcasts.

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 exist, so the description carries full burden. It discloses admin requirement, creation action, and mandatory unsubscribe, but lacks detail on side effects, permissions, or return behavior beyond these.

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 concise sentences with key information front-loaded. No wasted words; 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 complexity (6 parameters, nested objects, no output schema), the description covers the two modes and step structure well. It does not explain return values, but that is acceptable for a creation tool.

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

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

The description adds meaning beyond the schema by explaining step structure (subject, body_html, scheduled_at, day_offset/gap_days). Schema coverage is 83%, so the added context is valuable.

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 'Create' and resource 'scheduled email sequence', and distinguishes between two scheduling modes. It is specific and differentiates from siblings.

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 'Admin only' as a usage restriction, but does not explicitly compare with alternatives or state when not to use. The context is clear but lacks exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses the wildcard behavior for from_value and to_value, but does not mention potential side effects, authentication requirements beyond 'Admin only', rate limits, or whether the tool can update existing rules.

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 consists of three short sentences that are front-loaded with the action and condition. It is efficient and avoids fluff, though it could be slightly more structured.

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

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

Given the tool's complexity (8 parameters, nested objects, no output schema), the description explains the core trigger functionality and wildcard behavior. However, it lacks information about return values, the optional filter parameter, and whether it creates or updates triggers.

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 88%, so the schema already describes most parameters. The description adds no new information beyond what the schema provides (e.g., 'Empty from_value/to_value acts as wildcard' is already noted in parameter descriptions). It does not clarify the 'filters' object or other nested aspects.

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

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

The description clearly states the tool's purpose: 'Create an email rule that sends when a named variable changes from one value to another.' It uses a specific verb ('create') and resource ('email rule') with a distinct condition (variable change), distinguishing it from siblings like email_marketing_create_event_trigger.

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

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

The description includes the prerequisite 'Admin only,' which is helpful. However, it does not provide explicit guidance on when to choose this tool over alternatives (e.g., event triggers or broadcasts), nor does it mention when not to use 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?

No annotations provided, so description carries full burden. Clearly indicates a read-only inspection operation. Does not detail side effects, authentication specifics beyond 'Admin', or rate limits, but for a simple status check the transparency 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?

Single sentence, no redundancy, every phrase adds detail. Efficiently conveys purpose and scope without unnecessary 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?

Given zero required parameters and no output schema, the description adequately covers what the tool inspects. Could optionally mention return format, but as a status inspection, current completeness 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?

Schema provides full coverage (100%) for the single parameter include_logs. Description adds no extra meaning beyond what the schema already states; 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?

Description uses specific verb 'inspect' and clearly identifies the resource 'Email Marketing module', listing distinct aspects (enabled state, sender settings, etc.). This differentiates it from sibling tools which target specific configurations or actions.

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 'Admin only', indicating intended user role. While it doesn't contrast with alternatives, the list of inspected items implies it's a general overview tool, distinct from sibling tools that handle specific tasks.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is admin-only and manually fires rules, but does not describe side effects (e.g., email sends), idempotency, or error handling. The description offers minimal behavioral context beyond the immediate action.

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

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

The description is very concise with two sentences. It front-loads the critical constraint 'Admin only' and presents the purpose and use cases without unnecessary details.

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

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

Given 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the 'variable-transition' concept, what happens after firing (e.g., email sent, return value), or error conditions. For a destructive action tool, more context is needed.

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 baseline is 3. The description does not add meaning beyond what the schema provides (e.g., 'context' as extra template variables, 'user_id' as platform user id). No additional insight is given.

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 'fire' and the resource 'variable-transition email rules for one user'. It distinguishes from siblings by specifying 'manually fire' vs. 'create' triggers, and notes admin-only access and use cases for MCP/agent workflows and tests.

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 context by stating 'Admin only' and 'Useful for MCP/agent workflows and tests', implying it's for manual triggering. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'email_marketing_create_variable_trigger'.

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

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

With no annotations, the description adds critical behavioral context: 'Admin only' (permission requirement) and 'The unsubscribe block is still appended by the server' (important side-effect when updating body_html). This goes beyond what the schema provides.

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 long, front-loads the key permission constraint ('Admin only'), and every sentence provides distinct, valuable information with no redundancy or 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?

Given no annotations and no output schema, the description adequately covers purpose, usage, permission, and a crucial behavioral caveat. It could mention error handling or default values, but is largely complete for a straightforward update tool.

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

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

The input schema has 100% description coverage for all 4 parameters. The description adds extra context about the unsubscribe block, which relates to the body_html parameter, and mentions the template_id example. This adds value beyond 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 ('Update'), the resource ('automatic Email Marketing template'), and provides a concrete example ('user_joined welcome email'). It distinguishes this tool from sibling tools that handle broadcasts, sequences, etc.

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 notes that this is 'Admin only,' indicating who should use it. It gives an example of the template type. However, it does not explicitly state when to use this tool versus alternatives like creating a new template or using broadcast tools.

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

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

With no annotations provided, the description takes on full responsibility for disclosing side effects. It explicitly states 'Spends nothing', which conveys a non-destructive, read-only behavior, and clarifies that it only prices without generating. It also highlights what will be returned (duration, resolution, charge), providing transparent behavioral expectations.

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 only two sentences, with the primary purpose front-loaded in the first sentence. Every sentence earns its place: the first defines the action, the second lists outputs and confirms no charge. There is 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?

For a simple pricing tool with no output schema, the description is complete. It clearly states the tool's purpose, its return values, and its side-effect-free nature. The input schema covers parameter details, so no additional context is needed for an agent 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?

The input schema already provides 100% coverage for all three parameters (model, duration, resolution) with clear descriptions. The description adds no additional parameter-specific meaning beyond restating 'duration and resolution' in the return context, which does not significantly enhance the schema's provided semantics.

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

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

The description clearly states the tool's purpose with a specific verb ('Price') and resource ('video render'), and distinguishes it from sibling tools like generate_video by explicitly saying 'before generating it'. It also specifies what it returns, leaving no ambiguity about the tool's function.

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

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

The phrase 'before generating it' provides clear when-to-use context, indicating this is a pre-flight cost check. However, it does not explicitly name alternative tools or state when not to use it, though the context is strong enough for an agent to infer the appropriate usage.

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

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

With no annotations, the description carries the transparency burden. It discloses cost behavior (free plans burn monthly images, paid plans spend credits), the return of a public URL, and the purpose of reference images for consistency. It does not detail rate limits, processing time, or failure modes, but the provided context is significantly more than minimal.

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-loaded with core purpose and output, followed by cost context and optional feature. Every clause contributes useful information without redundancy, making it concise and well-structured.

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

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

For a tool with 6 parameters and no output schema, the description covers key operational aspects: what it generates, cost implications, output format, and reference image usage. It omits potential wait times or job status, but the essentials for selection and invocation are 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that reference images are used to maintain consistency of a person, product, place, or brand, which enriches the reference_image_url parameters. It does not redundantly restate schema descriptions, adding value modestly.

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 ('Generate') and resource ('one marketing image'), listing concrete use cases (ad creative, thumbnail, hero, social graphic) and the output (public URL). This clearly distinguishes it from sibling tools like generate_video or generate_slideshow.

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

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

The description implies usage for static marketing images but does not explicitly state when to prefer this tool over alternatives such as generate_video or generate_slideshow. There is no explicit exclusion or mention of alternative tools, leaving usage context partially implied.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It openly states credit costs (1 platform credit, 1 extra per slide for rendering), that it returns the script for review, and that image rendering is async requiring polling. It does not mention authorization, rate limits, or failure modes, but the cost and workflow details are valuable and go beyond minimum expectations.

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. It front-loads the core purpose, then details cost, optional rendering, polling, and ID validation. Every sentence adds operational 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?

The description covers the main workflow and cost structure, but it does not specify the exact return format. Since there is no output schema, the phrase 'returns the script for review' is ambiguous—does it return a plain-text script, an object with an ID, or both? An explicit mention of the response identifier needed for polling get_slideshow would close this gap. Given the tool's complexity (20 params), this is a noticeable 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context by explaining how render_images triggers immediate rendering, that get_slideshow should be polled for status, and that list_media_capabilities is the source for valid style/template/collection identifiers. This helps agents understand parameter relationships beyond the schema alone.

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

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

The description opens with a specific verb+resource: 'Write a TikTok/Instagram-style slideshow' and enumerates concrete outputs (hook, per-slide copy, caption, hashtags). It distinguishes itself from sibling media tools like generate_image and generate_video by focusing on the slideshow script format, and it clearly states the language support and review-first 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 gives explicit workflow guidance: set render_images=true to start rendering, poll get_slideshow until 'ready', and call list_media_capabilities for valid style/template/collection IDs. It names alternative tools to use in the pipeline, though it doesn't explicitly state when NOT to use this tool (e.g., for video or single images).

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

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

With no annotations provided, the description carries the full transparency burden. It discloses asynchronous submission, immediate job_id return, spending from a prepaid video-credit wallet (not platform credits), invitation gating, and a recommendation to cap spend via max_charge_usd—all 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?

Three sentences, each serving a distinct purpose: definition, async workflow/status polling, and cost/access caveats. 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?

The description compensates for the absent output schema by clearly stating it returns a job_id and directing to get_video_status. It covers async behavior, cost implications, and invitation gating. It could mention estimate_video_cost for cost pre-check, but overall it is quite complete for an async job submission tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds slight emphasis on max_charge_usd for autonomous agents but doesn't substantially deepen understanding of the other parameters beyond their existing 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 states 'Generate an AI video from a text prompt' with a specific verb and resource. It clearly distinguishes from sibling tools like generate_image and generate_slideshow by media type and the async job 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 describes when to use the tool by outlining the asynchronous workflow (returns job_id, poll get_video_status) and important cost/access caveats (prepaid video-credit wallet, invitation gating). However, it doesn't explicitly mention alternatives like estimate_video_cost for pre-checking costs or how it compares to generate_slideshow.

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 accurately portrays a read operation without side effects, but given the lack of annotations, it does not disclose potential behaviors like rate limits, data freshness, or error handling for missing tests.

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 single clear sentence with no fluff. It could be slightly more detailed but remains efficient and front-loaded with the core purpose.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is complete enough to understand what it returns. It assumes the test exists, which is reasonable for a stats retrieval tool.

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

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

The input schema already has descriptions for both parameters (app_id and test_id) with 100% coverage. The description adds no additional meaning 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 clearly states the verb 'Get' and specifies the exact resources (views, unique visitors, conversions, conversion rates) for an A/B test, distinguishing it from sibling tools like list_ab_tests or create_ab_test.

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 (when you need A/B test metrics) but lacks explicit guidance on prerequisites, such as requiring the test to exist or be active, and does not mention alternative tools for similar tasks.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the data returned (entities, pages, etc.) but does not mention any behavioral traits such as whether it's read-only (likely) or any permissions/rate limits.

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

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

Two sentences with clear structure: first defines the scope, second provides usage guidance. No redundant or extraneous 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?

Despite only one parameter and no output schema, the description sufficiently conveys that the tool returns a comprehensive overview. For a holistic inspection tool, this is complete enough for an agent to use 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 has 100% coverage with one parameter 'app_id' described. The description does not add additional meaning or usage notes beyond the schema, which is adequate but not enhanced.

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 it provides 'deep introspection' of an app and lists specific aspects (entities, pages, settings, integrations, environment variables, file structure), which distinguishes it from sibling tools like get_pages or list_integrations.

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 advises using this tool 'before updating' an app, giving a clear context. However, it does not specify when not to use it or mention alternative tools, which would be helpful given the many sibling inspection tools.

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

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

With no annotations, the description carries full burden. It states the output (file tree with paths and sizes) but does not disclose whether this is a read-only operation, any side effects, or authorization requirements. The description is minimal and lacks behavioral context.

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

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

The description is a single, direct sentence with no unnecessary words. It is front-loaded and conveys the essential information efficiently.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the tool's purpose and return payload. However, it could mention the format of the file tree (e.g., nested structure) or behavior for empty apps.

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% with one parameter 'app_id' described as 'The app ID'. The description adds no additional meaning beyond the schema, so baseline score 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 tool retrieves a file tree for an app, specifying the data returned (paths and byte sizes). It distinguishes from siblings like 'read_app_file' (single file) and 'read_app_files' (possibly different listing).

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

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

No explicit guidance on when to use this tool vs alternatives. There is no mention of prerequisites, limitations, or when not to use it. The only context is the required app_id from the schema.

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

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

With no annotations, the description must fully convey behavioral traits. It indicates the tool reads app settings and returns derived information (links with access flags), suggesting a read-only operation. However, it does not mention required permissions, potential errors, rate limits, or that the app must exist. The description is adequate but not exhaustive.

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 single sentence that efficiently lists all the items returned. It is front-loaded with the verb and resource, and every element of the sentence adds value. It could be slightly more terse, but it avoids unnecessary 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?

Given the absence of an output schema, the description gives a good overview of what is returned (types of links and access info). However, it does not specify the exact format (e.g., object keys, data types). For a tool with moderate complexity, this is mostly complete but could benefit from additional structure hints.

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 covers 100% of parameters, describing 'app_id' as 'The app ID'. The description does not add any additional meaning or formatting details for the parameter beyond what the schema provides. Thus, it meets the baseline but adds no extra 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 clearly states the tool returns editor, preview, published path, subdomain, and custom-domain links along with access information. It uses a specific verb ('Return') and resource (links), and distinguishes itself from siblings like get_preview_url and list_app_domains by aggregating multiple link types and access conditions.

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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., get_preview_url for a single preview URL, or list_app_domains for domains). It implies use for comprehensive link retrieval, but lacks exclusion criteria or context.

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

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

With no annotations, the description must disclose behavioral traits. It only says 'Read', implying idempotency, but lacks details on data recency, pagination, permissions, rate limits, or what 'recent' means. The behavioral disclosure is insufficient.

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

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

The description is one sentence of 8 words, concise and front-loaded. No unnecessary text, but it could be slightly more structured to include key details without adding length.

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 simplicity (2 params, no output schema, no annotations), the description is minimal but conveys the core purpose. However, missing details about time range, output format, and pagination leave it incomplete for effective use.

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

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

Schema description coverage is 50% (only app_id described). The description does not add meaning to the parameters beyond the schema. 'limit' is not explained, and 'app_id' is simply restated. The purpose statement does not compensate for missing parameter documentation.

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

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

The description clearly states 'Read recent server-side security audit events for an app.' It specifies a verb (Read), a specific resource (security audit events), and a scope (for an app), distinguishing it from sibling tools like 'get_app_security_context'.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or when not to use it, which is necessary given the presence of siblings like 'get_app_security_context'.

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

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

With no annotations provided, the description effectively discloses the tool's read-only nature ('safe security context'), lists what is included and excluded (no secrets, no access to other apps), and implies non-destructiveness. It lacks details on authentication requirements or pagination but is sufficient for basic behavioral understanding.

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

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

The description is a single, well-structured sentence that front-loads the purpose and includes a bullet-like list of returned items and an exclusion. Every phrase adds value with no 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 absence of output schema and annotations, the description adequately covers the tool's behavior and output composition. However, it omits explanation of the audit_limit parameter and does not specify the exact structure of the returned data, leaving minor gaps.

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

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

Schema description coverage is 50% (only app_id described in schema). The tool description does not mention either parameter (app_id or audit_limit), failing to add meaning beyond the schema. Since coverage is not high, the description should compensate but does not, resulting in poor parameter semantics.

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

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

The description uses the specific verb 'Return' and resource 'safe security context for one owned app', listing explicit components (owner, collaborators, members, policies, audit). It clearly distinguishes from related sibling tools like get_app_security_audit by stating it returns a broader context.

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

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

The description implies the tool is for owned apps only and states it does not return secrets or grant access to other apps, providing clear situational cues. However, it does not explicitly contrast with alternative tools or specify when not to use it, leaving some 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?

No annotations are provided, so the description carries the burden. It implies a read-only operation (retrieving an overview) and lists return components, but does not explicitly confirm idempotency, side effects, or authorization needs. The behavioral disclosure is adequate but not thorough.

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 single sentence with a clear colon-separated list of included elements. No unnecessary words, efficiently conveying the tool's purpose and scope.

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, the description adequately covers the main return fields. However, it could be more complete by mentioning the response structure or format, but given the tool's simplicity, it is nearly 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?

The single parameter 'app_id' is fully described in the schema (100% coverage). The description adds no additional meaning or context beyond the schema, such as format, validation, or how to obtain the ID. Baseline score 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 tool retrieves an app overview covering files, published state, URL, and active jobs. It uses a specific verb-resource combination ('Get app overview') and lists the components, which distinguishes it from siblings like get_app_detail or get_job_status, though not explicitly.

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 on when to use this tool versus alternatives like get_app_detail or get_app_files. The description does not mention prerequisites, limitations, or exclusion criteria, leaving the agent without 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?

With no annotations, the description should disclose behavioral traits. It only states the output but does not mention read-only nature, authentication needs, or error cases. Minimal transparency.

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

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

Single sentence, no wasted words, front-loaded with key action and output.

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 no output schema, the description does not detail the structure of the returned SSL status or DNS records. Adequate but not complete for a tool with no output 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 covers both parameters with descriptions. The description adds context that the DNS records are for 'pending certificate validation,' enhancing understanding of the domain parameter's role.

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 it returns SSL/certificate status and pending validation DNS records for the app custom domain, distinguishing it from sibling tools like check_domain_verification and list_app_domains.

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 on when to use this tool versus alternatives like check_domain_verification or get_domain_verification. Does not specify prerequisites or conditions.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It indicates a read operation (returning records and instructions), but does not disclose any preconditions or side effects. For a simple retrieval, this is adequate but could be more transparent about error scenarios or state dependencies.

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 single sentence of 14 words, highly efficient with no wasted words. However, it omits some context that would improve usability, so it is not a perfect 5.

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 absence of an output schema, the description partially explains the return value (DNS records and instructions) but does not specify the format or cover error conditions. It is moderately complete for a straightforward retrieval tool.

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

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

The input schema covers all parameters with descriptions (100% coverage). The tool description adds no extra 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 uses a specific verb 'Return' and identifies the resource as 'exact DNS records and instructions' for custom domain verification. It clearly states what the tool does, but it does not explicitly differentiate from sibling tools like 'check_domain_verification' or 'add_custom_domain'.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., check_domain_verification, list_app_domains). There is no mention of prerequisites, such as requiring the domain to be already added, or when this should be called in a workflow.

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