Vee3

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

With no annotations, the description carries the burden. It discloses that the tool creates a domain, returns the created domain with CNAME targets, and notes a cost of 10 tokens. It does not discuss authentication requirements or failure modes, but it is transparent about the primary side effect and output.

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 four short sentences, each adding value: purpose, prerequisite/guidance, return info, and cost. No fluff or repetition of schema details.

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

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

For a 4-parameter creation tool with no annotations, the description covers the prerequisite (get_connected_accounts), key parameter behavior (clerk_instance_id), return value (CNAME targets), and cost. It doesn't explain is_satellite's full implications, but the schema covers the basics, and the output schema handles return format details.

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

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

Schema descriptions cover all 4 parameters, so the baseline is 3. The description adds extra meaning for clerk_instance_id by clarifying the default-account behavior, which goes beyond the schema. It also clarifies proxy_url's role in satellite domain setups.

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 'Add a custom domain to a connected Clerk instance' with a clear verb and resource. It also distinguishes itself by noting it returns CNAME targets for DNS setup, setting it apart from sibling tools like change_instance_domain or update_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?

Explicitly instructs to call clerk.get_connected_accounts first and explains how to use clerk_instance_id to target a specific connection or omit it for the default account. This provides clear context for when and how to use the tool, though it doesn't mention alternatives 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?

With no annotations, the description carries the full burden. It discloses the effect (prevents sign-in), the return format (updated summaries and total count), a prerequisite (get_connected_accounts), and cost. It does not mention reversibility or auth requirements, but these are not critical for basic 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?

The description is four short, information-dense sentences covering the action, prerequisite, return value, and cost. Every sentence earns its place with no unnecessary 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 an output schema exists and parameters are fully described, the description covers the essential behavioral aspects: effect, return, prerequisite, and cost. It could optionally mention that unban_users reverses the action, but it is complete enough for selecting and invoking the tool correctly.

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

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

Schema coverage is 100%, and the description largely mirrors the schema's own parameter descriptions (e.g., clerk_instance_id). It adds minimal new meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool bans one or more Clerk users and prevents them from signing in, which is a specific verb+resource combination. It distinguishes from sibling tools like clerk.unban_users and clerk.delete_user by focusing on the ban action and its immediate effect.

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 provides explicit guidance to call clerk.get_connected_accounts first and explains how to target a specific connection or use the default account. It does not explicitly compare with alternatives like unban_users or delete_user, but the context is clear and actionable.

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

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

With no annotations, the description fully discloses the destructive nature, consequences (invalidates active sessions, brief downtime), and return meaning (whether Clerk accepted the request). It also mentions token cost. This goes beyond basic safety flags and gives the agent critical operational knowledge.

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

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

The description is compact and front-loaded, with each sentence serving a purpose: purpose, warning, prerequisite/instructions, return value, and cost. No filler or redundant repetition of schema 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 the tool's complexity, the description covers purpose, safety warning, prerequisite call, parameter targeting logic, and return semantics. With an output schema present, it does not need to detail return structure. The description is complete enough for an agent to invoke safely and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds no new parameter details beyond restating the clerk_instance_id guidance already present in the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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: 'Change the primary or secondary home URL for a connected Clerk instance.' This clearly distinguishes it from sibling domain tools like clerk.update_domain or clerk.add_domain by focusing on the connected instance's home URL.

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

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

The description provides clear usage context: it warns that this is destructive, instructs to call clerk.get_connected_accounts first, and explains how to target a specific connection via clerk_instance_id. However, it does not explicitly state when not to use it or name alternative tools for domain management.

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 discloses a concrete behavioral trait: 'Cost = 2 tokens' and implies performance trade-offs (cheaper). However, it doesn't mention auth requirements or error conditions, which are common for Clerk tools, but for a simple count it's reasonably transparent.

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

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

Three sentences, front-loaded with the primary purpose, followed by actionable usage steps and cost. Every sentence provides unique value with no padding.

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

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

Given the tool's simplicity (count operation, two optional params, output schema present), the description fully covers the essential guidance: prerequisite, default behavior, cost advantage, and parameter handling. It is complete and self-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 coverage is 100% and descriptions already explain both parameters, but the tool description adds useful context: 'clerk_instance_id' targets a specific connection and omitting uses the default account, plus 'query' is for optional filtering. This enriches the meaning beyond raw 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 'Return the total number of users in a connected Clerk application' with a specific verb and resource. It distinguishes itself from sibling tools like clerk.list_users by emphasizing it only returns a count, not the list.

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

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

Provides explicit usage guidance: 'Call clerk.get_connected_accounts first' is a clear prerequisite, and explains when to pass or omit clerk_instance_id. Also states a decision heuristic: 'Cheaper than listing users when you only need the total count' directly contrasts with the alternative clerk.list_users.

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 does an excellent job by flagging the token as a sensitive, high-privilege secret and warning against logging or exposing it. It also discloses the token cost and the prerequisite call to get_connected_accounts. It doesn't mention rate limits or error behavior, but those are less critical given the security warnings and output schema.

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

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

The description is concise and well-structured: a clear purpose statement, a bold security warning, a brief usage instruction, and a cost note. Every sentence serves a distinct purpose with no redundancy. The most important information (what the tool does) is front-loaded.

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

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

Given the tool's sensitivity and complexity (5 parameters, security implications), the description is remarkably complete. It covers purpose, prerequisite, security handling, cost, and connection selection. The output schema exists to explain return values, and the schema covers all parameters, so the description fills the remaining gaps effectively.

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

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

The input schema has 100% description coverage, with each parameter already explained in detail (e.g., user_id, actor_sub, clerk_instance_id). The description adds marginal value beyond the schema, such as reinforcing the use of clerk_instance_id for targeting a specific connection. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's specific function: creating an actor token for impersonation. The verb 'Create' plus the resource 'actor token' and the purpose 'lets one user impersonate another' make it unambiguous. It also distinguishes this from sibling token tools like create_m2m_token or create_session_token by emphasizing impersonation.

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 a clear usage context: it instructs the agent to call clerk.get_connected_accounts first and explains how to choose the connection via clerk_instance_id. While it does not explicitly name alternative tools to avoid, the prerequisite and connection targeting give solid practical guidance. Missing explicit 'when not to use' but enough context for correct invocation.

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

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

No annotations, but description carries burden well: highlights that the token is a sensitive single-use secret and warns against logging. Also discloses cost and prerequisite, adding useful context 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?

Four concise sentences, each with distinct value: purpose, security warning, usage prerequisite, cost. Front-loaded, no 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 high schema description coverage and presence of output schema, the description covers the key aspects: purpose, security, prerequisite, instance targeting, and cost. No major gaps for a token 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?

Schema covers all 5 params at 100%, so baseline is 3. The description adds meaningful guidance for clerk_instance_id (how to obtain via get_connected_accounts, default account behavior) beyond the schema.

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

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

Clearly states the tool creates an admin portal link token in a connected Clerk instance. Distinguishes from sibling token tools (actor, session, sign-in, m2m) by naming the specific resource.

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

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

Provides explicit prerequisite: call clerk.get_connected_accounts first. Explains when to pass clerk_instance_id vs omit. No explicit alternatives, but the context is clear enough for this specialized token tool.

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

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

With no annotations, the description carries the full burden. It discloses the prerequisite call, instance targeting behavior, that a summary is returned, and includes 'Cost = 8 tokens.' This goes beyond the schema. However, it omits potential edge behaviors (e.g., duplicate handling, required permissions), which a fully transparent description could include.

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

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

The description is compact and well-structured: purpose first, then prerequisite/parameter guidance, return value, and cost. Every sentence serves a functional purpose with no filler. The cost line is an efficient addition.

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 operation is simple, and the description covers purpose, prerequisite, instance selection, return, and cost. An output schema exists, so return details are covered. Minor gaps remain around when to choose this over blocklist tools and potential duplicate behavior, but overall it is sufficiently complete for a 3-parameter 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for clerk_instance_id by explaining when to pass it and the default behavior, and it stresses calling get_connected_accounts first. This nudges the score above baseline, though it does not elaborate on identifier or notify beyond the schema.

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

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

The description clearly states the tool's action: 'Add an identifier to the allowlist in a connected Clerk instance.' The verb 'Add' and resource 'identifier to the allowlist' are specific, and the phrase 'allowlist' distinguishes it from the sibling create_blocklist_identifier tool. The mention of 'connected Clerk instance' scopes it appropriately.

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

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

The description provides explicit usage context: 'Call clerk.get_connected_accounts first' and explains how to use clerk_instance_id (pass to target a specific connection, omit for default). However, it does not explicitly state when to use this tool over alternatives (e.g., vs create_blocklist_identifier), so it falls just short of a 5.

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

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

Description highlights that the 'returned secret is a high-privilege credential; do not log or expose it' — a valuable safety disclosure. It also states the return type and token cost. However, since no annotations are provided, the description does not mention permissions required, reversibility, or side effects beyond creation; it relies on the obvious 'create' semantics.

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?

Description is compact, with each section (action, sensitive warning, prerequisite, return, cost) serving a distinct purpose. Clear formatting with line breaks and bold makes it scannable.

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

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

For a mutation tool with zero annotations and 9 parameters, the description provides key context: sensitivity, prerequisite, instance selection, and return type. The output schema covers return details, and params are fully specified in schema. Missing alternative guidance is a minor gap, but overall 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?

Input schema already describes all 9 parameters with 100% coverage, so the description adds little beyond the 'clerk_instance_id' guidance already present in the schema. The description doesn't enrich parameter meanings beyond what the schema provides.

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

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

Clearly states 'Create an API key in a connected Clerk application' — a specific verb and resource. Among many create_* siblings, it does not explicitly distinguish from token creation tools like create_m2m_token or create_session_token, but the target is unambiguous.

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

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

Provides explicit prerequisite: 'Call clerk.get_connected_accounts first.' Also explains instance targeting: 'Pass clerk_instance_id to target a specific connection, or omit it to use the default account.' No mention of when to choose this over alternative credential-creation tools, but the context is 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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral consequence (blocked identifiers cannot sign up or sign in), states the return value (created blocklist identifier summary), and includes cost. It does not mention reversibility or idempotency, but for a create operation this is reasonably transparent.

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 efficient and well-structured: it opens with the purpose, then gives the prerequisite, targeting logic, behavioral effect, return value, and cost. Every sentence adds necessary information 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?

For a tool with 2 parameters (1 required) and a rich schema, the description covers the full workflow: how to select the instance, what the operation does, and what is returned. The existence of an output schema means return details do not need to be expanded. The cost note also adds practical context.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents both parameters. The description adds little beyond the prerequisite to call get_connected_accounts first, which is more usage guidance than parameter semantics. It does not enhance meaning of the parameters beyond what the schema provides.

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

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

The description clearly states the tool's action ('Add an identifier to the blocklist') and the specific resource ('blocklist identifier in a connected Clerk instance'). It distinguishes from sibling tools like create_allowlist_identifier by specifying the blocklist and the effect that blocked identifiers cannot sign up or sign in.

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

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

The description gives clear context: it explains the prerequisite to call clerk.get_connected_accounts first, and how to target a specific instance or default. It does not explicitly mention alternatives or exclusions, but the usage context is unambiguous. This is more than implied usage but lacks explicit alternative comparison.

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

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

With no annotations, the description carries the full burden. It discloses the return value ('Returns the created email address summary') and cost, and mentions a prerequisite call, but doesn't elaborate on side effects like verification emails or permissions. It provides some context but not rich 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?

The description is concise and well-structured: purpose sentence, prerequisite/instance guidance, return summary, and cost. Each sentence earns its place with no unnecessary 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 5-parameter schema with 100% coverage and the presence of an output schema (mentioned but not shown), the description covers the critical flow: what it does, the required first call, instance selection, and return value. It could mention side effects or permissions, but overall it's sufficiently complete for the complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a bit of context for clerk_instance_id (call get_connected_accounts first), but this is partly redundant with the schema description which already says 'Omit to use the default connected account.' No significant additional meaning 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 tool creates an email address for a Clerk user with a specific verb and resource. While it doesn't explicitly differentiate from sibling tools like create_phone_number, the resource is unambiguous and the name reinforces the purpose.

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

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

The description gives clear usage context by instructing to call clerk.get_connected_accounts first and explaining how to handle clerk_instance_id (target a specific connection or omit for default). It doesn't explicitly mention when not to use it or alternatives, so it stops short of a 5.

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

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

With no annotations, the description carries the burden. It discloses the return value ('Returns the new enterprise_connection summary'), the cost, and the prerequisite of a connected application. It does not discuss permissions, side effects beyond creation, or behavior differences between SAML and OIDC providers, making it minimally adequate.

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

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

The description is compact: a purpose sentence, a usage sentence, a return sentence, and a cost line. No wasted words, and the most important info is front-loaded.

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

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

Despite the 12-parameter schema, the description covers the essential usage flow (prerequisite, target selection) and return summary. The output schema handles return details, and parameter schema handles parameter docs. It lacks explicit alternative tool guidance, but overall it is sufficiently complete for an agent to invoke it correctly for the primary use case.

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

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

The input schema covers all 12 parameters with descriptions (100% coverage), so the baseline is 3. The description adds no extra parameter semantics beyond what the schema already provides; even the clerk_instance_id note is redundant with the schema text.

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

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

The description clearly states a specific action ('Create a SAML or OIDC enterprise SSO connection') with a target resource ('in a connected Clerk application'). This distinguishes it from related tools like update_enterprise_connection or test_run. The verb and resource are unambiguous.

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

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

The description provides clear contextual guidance: call clerk.get_connected_accounts first and optionally pass clerk_instance_id, with a fallback to the default account. However, it does not explicitly compare to alternative tools (e.g., test_run, list, update), so it falls short of explicit when/when-not guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses the return value ('short-lived url') and implies a test flow, but does not mention potential side effects such as creating a test run record (suggested by sibling list_enterprise_connection_test_runs) or any required permissions. This is useful but incomplete.

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

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

Four sentences, front-loaded with the main purpose, and no wasted words. Each sentence adds meaning: purpose, prerequisite/parameter usage, return value, and cost. Ideal conciseness for a tool of this complexity.

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 an output schema present, the description doesn't need to detail return structure. It covers the prerequisite, how to target a connection, and the nature of the return. Could mention side effects or the connection_id format, but overall it is complete enough for this simple 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 a baseline of 3 applies. The description adds value by instructing to call get_connected_accounts first and clarifies when to pass clerk_instance_id, supplementing the schema's parameter descriptions and providing context beyond the schema.

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

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

The description clearly states the action: 'Start an SSO test flow for an enterprise connection in a connected Clerk application.' It uses specific verb+resource and distinguishes from siblings like create_enterprise_connection or list_enterprise_connection_test_runs by focusing on the test flow initiation.

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

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

Provides explicit usage context with 'Call clerk.get_connected_accounts first' and explains how to choose the clerk_instance_id ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account'). It lacks explicit when-not-to-use or alternative tool suggestions, but the clear prerequisite and parameter guidance make it a 4.

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 transparency burden. It discloses the operational cost (10 tokens) and the need for a connected account, but doesn't mention side effects like email sending, idempotency, or revocation options. This is useful 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?

Three concise sentences covering purpose, usage prerequisite/parameter guidance, and cost. Every sentence is informative with no filler or repetition.

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

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

With an output schema present and a clear description covering the main flow (get_connected_accounts → choose instance → invite), this is complete enough for an agent to use correctly. It might mention alternative invitation tools, but that's not essential.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description reinforces the clerk_instance_id default behavior and the 'one or more' nature of invitations, but adds little beyond the schema's own parameter descriptions.

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

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

The description clearly states the tool's function with the specific verb 'invite' and resource 'email addresses to sign up for a connected Clerk application.' It distinguishes itself from sibling tools like create_organization_invitations by specifying the context of a connected Clerk application.

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 provides an explicit prerequisite ('Call clerk.get_connected_accounts first') and explains how to choose the clerk_instance_id parameter. While it doesn't name alternative tools or exclusions, the usage context is clear for selecting this tool.

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

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

No annotations are provided, so the description must disclose behavior. It states the return behavior ('Returns the new template summary') and the 10-token cost, but it does not discuss permissions, error conditions, or side effects beyond creating a template.

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 brief paragraphs, each serving a clear purpose: purpose, prerequisite/connection guidance, and return/cost. 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?

With a rich input schema and an output schema, the description provides the essential prerequisite and connection targeting logic. It is complete for a create tool, though it could mention potential error cases or duplicate-name behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for clerk_instance_id ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account'), which goes beyond the schema's 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 opens with a specific verb+resource: 'Create a new JWT template in a connected Clerk application.' This clearly states the tool's function and distinguishes it from sibling tools like update_jwt_template or delete_jwt_template.

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

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

It explicitly instructs to call clerk.get_connected_accounts first and explains how to target a connection (via clerk_instance_id or default). This gives clear usage context, though it does not explicitly compare to alternatives like other token-creation 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 present, the description adds important behavioral context by flagging the token as 'high-privilege secret' and instructing not to log or expose it. It also discloses the 'Cost = 15 tokens' operational cost. However, it doesn't describe token lifecycle details like revocation, but the schema and sibling tools partially cover that.

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

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

The description is compact and front-loaded: the purpose is stated in the first sentence, followed by a crucial security warning, usage steps, return value, and cost. Each sentence earns its place with no redundant filler.

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

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

The description covers the essential aspects: what it creates, sensitivity handling, prerequisite steps, instance selection, and cost. The output schema exists and all parameters are documented, so the description doesn't need to explain return values in detail. It could expand on post-creation lifecycle (e.g., revocation), but overall it's adequate for correct invocation.

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

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

All six parameters have descriptions in the schema (100% coverage), so the schema carries the semantic burden. The description largely restates clerk_instance_id guidance already in the schema, adding only the prerequisite call to get_connected_accounts. No new parameter-specific meaning is provided beyond the schema.

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

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

The description clearly states the action: 'Create an M2M token in a connected Clerk instance.' It names the specific resource type (M2M token) and context, but doesn't explicitly compare against sibling token-creation tools like create_actor_token or create_session_token, so it doesn't fully achieve sibling differentiation.

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

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

It provides a clear precondition: 'Call clerk.get_connected_accounts first.' It explains how to choose a connection with clerk_instance_id or omit it for the default, giving concrete usage context. It doesn't state when not to use it or list alternative tools, but the guidance 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 disclosure burden. It warns that the response may include a sensitive secret_key, advising not to log or expose it, and notes the token cost. This is valuable context, though it could go further by mentioning permission requirements or idempotency.

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

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

The description is concise and well-structured: it starts with the core purpose, then highlights the sensitive nature, prerequisites, and cost. Every sentence adds information without unnecessary bloat.

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 prerequisites, sensitive return value, and cost, and the output schema presumably handles return format. It does not mention potential errors or rate limits, but for a creation tool with rich schema and clear usage, 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 description coverage is 100%, so the schema already documents all parameters with clear descriptions. The tool description adds only a hint about clerk_instance_id usage, which is helpful but does not significantly enrich parameter meaning beyond the schema's baseline.

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

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

The description clearly states the verb and resource: "Create a machine in a connected Clerk instance for machine-to-machine authentication." It specifies the purpose (M2M auth) and distinguishes this from sibling tools like create_m2m_token (which creates a token, not a machine) and create_api_key.

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 provides explicit when-to-use guidance by instructing to call clerk.get_connected_accounts first and explaining how to target a specific instance versus the default. It does not explicitly mention when not to use this tool or alternatives, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the burden. It discloses the return value ('Returns the created machine scope') and the token cost, plus the prerequisite. However, it doesn't mention potential side effects beyond creation, error conditions, 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?

Four concise sentences, front-loaded with the core purpose. Every sentence provides value, including the prerequisite, parameter guidance, return value, and cost. No 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?

For a 3-parameter create tool with an output schema, the description covers the essential usage context: purpose, prerequisite, parameter selection, and return. It could mention error cases but is otherwise sufficiently 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%, but the description adds meaningful context for the optional parameter clerk_instance_id, clarifying when to use it vs omit. This goes beyond the schema's basic field 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 a specific action ('Create a machine scope') with a clear resource and purpose ('so one machine can access another'). It distinguishes from siblings like create_machine or delete_machine_scope by clarifying this is about granting access between machines.

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

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

Provides prerequisite guidance ('Call clerk.get_connected_accounts first') and explains the optional parameter selection (use clerk_instance_id for a specific connection or omit for default). It doesn't explicitly mention alternatives, but the context is 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that client_secret may be present and should not be logged, that a prior call to get_connected_accounts is required, that omitting clerk_instance_id uses the default account, and that it returns an OAuth application summary. It also states the token cost. This goes beyond the schema and provides valuable safety and operational context.

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

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

The description is four concise sentences with no filler. It is front-loaded with the purpose, then provides a security warning, a prerequisite, and the return value. Every sentence adds meaningful information and is structured logically.

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 (6 parameters, output schema present), the description covers the essential aspects: purpose, prerequisite, security, return value, and cost. It doesn't discuss error conditions or specific parameter combinations, but the high schema coverage and output schema mitigate the need. Overall, the description is sufficiently complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the clerk_instance_id parameter behavior ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account') and by noting that client_secret may be present for confidential clients, which relates to the 'public' parameter. These insights complement the schema descriptions and aid the agent in parameter selection.

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 function: 'Create a new OAuth application in a connected Clerk application (Clerk as IdP)'. This is a specific verb+resource combination that distinguishes it from sibling create_* tools like create_api_key or create_user. The mention of 'connected Clerk application' adds context that uniquely identifies this tool's purpose.

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

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

The description provides explicit usage guidance: 'Call clerk.get_connected_accounts first' and explains how to target a specific connection via clerk_instance_id or use the default. It also warns about sensitive data handling. While it doesn't explicitly discuss alternatives or when not to use, the clear prerequisite and operational instructions give strong context for when this tool should be invoked.

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 discloses the operation's mutation nature ('Create'), returns a summary, and notes a token cost. However, it does not mention side effects, idempotency, permission requirements, or error conditions, which are relevant for a create operation. The cost disclosure adds some value, but deeper behavioral context is missing.

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 brief and well-structured: a one-sentence purpose, a prerequisite and usage note, a return-value sentence, and a token cost. No wasted words; every sentence contributes essential information and is front-loaded with 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 tool has an output schema, so return details are covered. The description provides the key prerequisite of calling get_connected_accounts first and explains how to select an instance. For a create tool with 7 parameters, the schema fully documents inputs, and the description adds operational context (prerequisite, cost), making it sufficiently complete. It could mention failure modes or uniqueness constraints, but these are not essential.

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

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

Schema description coverage is 100%, with every parameter individually described. The description reiterates the clerk_instance_id parameter's purpose but adds no new information beyond the schema. Since the schema fully documents parameters, a baseline of 3 is appropriate.

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

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

The description states a specific action: 'Create a new organization in a connected Clerk application.' It clearly identifies the resource (organization) and distinguishes it from sibling tools like create_organization_domain or create_organization_membership, avoiding ambiguity among the many create_* tools.

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

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

The description explicitly instructs to call clerk.get_connected_accounts first, establishing a prerequisite. It also explains how to select the target connection via clerk_instance_id, with a fallback to the default account. This gives clear context for when and how to invoke the tool, though it doesn't elaborate on when not to use it or alternative 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 bears the full burden. It discloses a prerequisite and the return value ('Returns the created domain summary'), but does not mention verification behavior, duplicate handling, or permission requirements. This adds useful context but is not exhaustive for a create operation.

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

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

Four sentences, each earning its place: purpose, prerequisite/guidance, return, and cost. It is front-loaded and concise with no 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?

The description covers all essentials for a moderate-complexity tool: what it does, the prerequisite, how to handle connection targeting, and what it returns. With full schema coverage and an existing output schema, no significant information gaps remain.

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 valuable meaning for clerk_instance_id ('Pass to target a specific connection, or omit to use the default account'), going beyond the schema's explanation. This enrichment justifies a 4.

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

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

The description opens with 'Add a domain to a Clerk organization,' a specific verb+resource that clearly defines the operation. It distinguishes itself from sibling tools like update/delete/list organization domains by using 'add' and specifying the resource.

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

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

Provides a concrete prerequisite ('Call clerk.get_connected_accounts first') and clear guidance on targeting connections via clerk_instance_id or using the default account. While it lacks explicit exclusions or alternative tool mentions, it gives strong contextual instructions for when and how to use this tool.

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

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

No annotations are provided, so the description must carry the behavioral transparency burden. It does disclose the return value ('Returns the list of created invitation summaries') and the prerequisite workflow, plus a token cost. However, it omits key behavioral traits such as whether emails are sent, whether invitations expire, or any permission requirements. It implies a mutation but doesn't fully describe 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 four sentences, each earning its place: purpose, prerequisite, return type, and cost. It is front-loaded with the core action and avoids redundancy with the schema. There is no fluff 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 schema fully describes parameters and an output schema exists, the description covers the essential context: what the tool does, what to call first, what is returned, and cost. It lacks caveats about invitation behavior (e.g., email delivery, expiration) but is generally complete for an agent to use the tool correctly.

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

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

The schema already has 100% parameter description coverage, so the baseline is 3. The description adds value beyond the schema by explaining the workflow for clerk_instance_id: 'Pass clerk_instance_id to target a specific connection, or omit it to use the default account,' and explicitly instructs to call clerk.get_connected_accounts first. This clarifies the optional parameter's role in multi-account contexts.

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

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

The description clearly states a specific action: 'Invite one or more email addresses to join a Clerk organization with specific roles.' It names the resource (organization) and distinguishes this from sibling tools like clerk.create_invitations (general invitations) and clerk.create_organization_membership (adding existing users). The verb 'invite' and the scope 'organization' make the purpose unambiguous.

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

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

The description provides clear context: it is for inviting email addresses to join an organization. It also gives a prerequisite instruction: 'Call clerk.get_connected_accounts first' and explains how to use clerk_instance_id. However, it does not explicitly name alternatives or state when not to use this tool, such as comparing to clerk.create_organization_membership for existing users.

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 return value ('Returns the created membership'), cost ('Cost = 10 tokens'), and prerequisite behavior (get_connected_accounts, default connection). Missing permission requirements and idempotency, but covers key operational context.

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

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

Four concise sentences, front-loaded with purpose, followed by prerequisite, return, and cost. Every sentence earns its place; 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 full input schema and an output schema, the description adds vital cross-tool dependency and default-instance behavior. It's sufficient for smooth invocation, though edge cases like existing memberships or admin permissions are not addressed.

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's note about clerk_instance_id primarily restates the schema's 'Omit to use the default connected account,' adding no new parameter-level meaning beyond reinforcing the prerequisite call.

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?

Opens with 'Add a user to a Clerk organization with a specified role' – a clear verb, resource, and scope. This distinguishes it from sibling tools like delete_organization_membership, update_organization_membership, and list_organization_memberships.

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

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

Explicitly instructs to call clerk.get_connected_accounts first and explains how to handle clerk_instance_id (target specific connection vs. default). However, it doesn't explicitly mention when to prefer this over alternatives like create_organization_invitations.

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 carry the behavioral disclosure burden. It discloses that the tool creates a permission, returns a summary, and costs 10 tokens, and it clarifies the prerequisite call. However, it omits details about permissions required, potential conflicts, or error behavior. It adds some value but lacks rich 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 three short, focused sentences plus a cost line. The purpose is stated first, followed by prerequisite and targeting instructions, then the return value and cost. Every sentence earns its place, and there is zero waste.

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

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

Given the tool's moderate complexity (4 params, 2 required) and the presence of an output schema, the description adequately covers the purpose, prerequisite, connection targeting, return value, and cost. It doesn't enumerate output fields, but that is covered by the output schema. It is complete enough for an agent to select and invoke the tool correctly, though it could mention edge cases or authorization requirements.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the clerk_instance_id guidance already present in the schema ('from clerk.get_connected_accounts. Omit to use the default...'), adding no new semantic meaning. It also does not elaborate on name, key, or description beyond the schema's minimal descriptions. Thus the description adds minimal parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: 'Create a new organization permission in a connected Clerk application.' This clearly distinguishes it from sibling tools like create_organization_role or create_organization, as it targets 'organization permission' specifically. It is precise and unambiguous.

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

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

The description provides clear usage context by instructing to call clerk.get_connected_accounts first and how to target a connection via clerk_instance_id. It also explains the fallback to the default account. It doesn't explicitly state when not to use the tool or list alternatives, but the guidance is sufficient for correct invocation.

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

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

No annotations are provided, so the description carries the behavioral burden. It adds value by disclosing the cost (10 tokens), the return value (new role summary), and the connection-selection behavior. It does not discuss failure modes or permissions, but the mutation is implied by 'Create' and the extra details go beyond the structured data.

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

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

Four terse, purposeful sentences: purpose, prerequisite/connection instruction, return value, and cost. Nothing is redundant or wasted, and the most important information is front-loaded.

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

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

The description provides the essential operational context: prerequisite call, default vs. targeted connection, return summary, and cost. Combined with the full schema coverage and output schema, this is sufficiently complete for reliable invocation, though error/duplicate-key behavior is not mentioned.

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 provides 100% description coverage for all six parameters, so the baseline is 3. The description only restates the clerk_instance_id behavior already present in the schema, adding no new parameter-level meaning.

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

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

The description uses a specific verb ('Create') and resource ('new organization role in a connected Clerk application'), making the tool's function unmistakable. It also clearly distinguishes this from sibling tools like create_organization_permission and update_organization_role.

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

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

It explicitly states a prerequisite: 'Call clerk.get_connected_accounts first.' It also clarifies how to target a specific connection vs. the default account. It does not enumerate alternatives, but the usage context is clear enough for an agent to execute correctly.

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

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

No annotations are provided, so the description must carry the transparency burden. It discloses the creation action, prerequisite call, connection selection, return value, and token cost. However, it omits potential side effects beyond creation (e.g., whether the number becomes verified immediately, what happens if the number already exists) and any error conditions, leaving noticeable 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 compact, four short lines, with the primary purpose stated first. Every sentence contributes essential information: function, prerequisite, return, and cost. There is no fluff or repetition of schema details.

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

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

Given the tool's moderate complexity (6 params, mutation, no annotations), the description covers the core aspects: purpose, prereq, connection handling, return summary, and cost. The schema fully documents parameters and an output schema exists, so the description is largely complete. It could be improved by addressing common failure scenarios, but it is well-rounded for an MCP 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?

All six parameters are fully described in the schema (100% coverage), so the description does not need to explain each one. It adds value by linking clerk_instance_id to clerk.get_connected_accounts and clarifying the default behavior, but otherwise it repeats schema information. The baseline of 3 is appropriate.

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

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

The description opens with 'Create a phone number for a Clerk user,' clearly identifying the specific verb, resource, and target. This distinguishes it from sibling tools like create_email_address or create_user. The additional connection context reinforces the tool's specific 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?

It explicitly instructs to call clerk.get_connected_accounts first and explains how to target a specific connection or use the default. This is clear prerequisite and usage context. However, it does not explicitly mention when not to use this tool versus alternatives, so it stops short of a 5.

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

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

There are no annotations, so the description carries the transparency burden. It discloses a cost ('Cost = 10 tokens') and return value ('Returns the created redirect URL'), but does not mention permissions, reversibility, or other side effects beyond the implicit mutation.

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 four succinct sentences, front-loaded with the core purpose. It includes token cost and return behavior without any wasteful or repetitive text.

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 two-parameter create tool with an output schema and full parameter descriptions, the description provides the necessary prerequisites and selection logic. It lacks comparative guidance against siblings but is otherwise 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 schema covers 100% of parameters, so the baseline is 3. The description reinforces the schema's guidance for clerk_instance_id but adds no new parameter-level detail 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 opens with a specific verb+resource: 'Add an allowed redirect URL to a connected Clerk instance.' This clearly distinguishes it from the many other create_* tools and states exactly what is being created.

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 provides a clear prerequisite ('Call clerk.get_connected_accounts first') and explains how to target a specific instance or use the default account. Without an explicit alternative or when-not-to-use, it stops short of the highest bar but offers clear context.

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

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

No annotations are present, so the description must carry the transparency burden. It does disclose the cost (10 tokens) and the return fields, but it does not mention permissions, side effects, or failure modes. This is a partial disclosure that leaves important behavioral aspects undocumented.

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 four sentences with no filler. The purpose is front-loaded, followed by a prerequisite, parameter guidance, return fields, and cost. Each sentence earns its place and the structure is clean and scannable.

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 low-complexity create tool with full schema and an output schema, the description provides the essential usage context (prerequisite, parameter behavior, return payload). It lacks error-handling notes or side-effect warnings, but it is reasonably complete given the tool's simplicity and the existence of an 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?

The input schema already covers both parameters with meaningful descriptions (user_id format, clerk_instance_id default behavior). The description adds a note to call get_connected_accounts first, but this is more of a usage guideline than additional parameter semantics. With 100% schema coverage, the baseline is 3, and the description does not significantly exceed that.

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 'Create a new session for a Clerk user in a connected Clerk application,' which clearly states the verb, resource, and scope. It distinguishes itself from sibling tools like clerk.create_session_token by focusing on the session object rather than a token.

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

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

The description provides an explicit prerequisite ('Call clerk.get_connected_accounts first') and explains when to pass clerk_instance_id versus omit it for the default account. It does not explicitly state when not to use this tool, but the context is clear enough for selection among similar create 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 the burden. It discloses the sensitive nature of the JWT, warns against logging/exposing it, specifies the return field (jwt), and mentions cost. This goes beyond the schema and provides important behavioral context, though it doesn't cover error cases or permissions.

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

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

Four short sentences: purpose, security warning, usage prerequisite + parameter guidance, return value + cost. Every sentence serves a purpose, well-structured and front-loaded.

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

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

With output schema present, return value details are covered. The description covers prerequisites, security, parameter targeting, and cost. It's sufficiently complete for a token-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?

Schema covers 100% of parameters with descriptions. The description adds a small amount of value by clarifying the prerequisite call and the default behavior for clerk_instance_id, but largely repeats the schema's info. It doesn't add detail for session_id beyond 'active session'.

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

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

States it creates a session token (JWT) for an active session in a connected Clerk application. This is a specific verb (create), resource (session token), and scope (active session, connected app), distinguishing it from sibling token-creation tools like create_sign_in_token or create_actor_token.

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

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

Gives clear context: call clerk.get_connected_accounts first, and explains how to target a specific connection with clerk_instance_id or fall back to default. It doesn't explicitly name alternatives, but the context is sufficient for an agent to know when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden and does well: it calls out the token as a high-privilege secret, one-time use, and warns against logging or exposing it. This is valuable behavioral context beyond the schema, though it omits potential auth prerequisites 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?

Four short, purposeful sentences: purpose, sensitivity warning, usage instruction, and cost. The description is front-loaded with the core action and contains 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?

Description covers purpose, sensitivity, prerequisite, and connection selection. Combined with the complete schema and output schema, it gives enough context to invoke correctly. Missing error cases or permission requirements, but these are not critical for a token-creation 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%, so baseline is 3. The description repeats the clerk_instance_id usage from the schema ('omit to use the default') and adds the get_connected_accounts prerequisite, but provides no new parameter-level meaning beyond the schema's own 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?

Description states a specific verb ('Create a sign-in token') and resource ('user in a connected Clerk application'), further clarifying that the token enables credential-free sign-in (magic-link style) and is one-time use. This clearly distinguishes it from sibling tools like create_session_token or create_actor_token.

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?

Description gives an explicit prerequisite ('Call clerk.get_connected_accounts first') and precise instructions for targeting a connection (pass clerk_instance_id or omit for default). It does not explicitly cite alternatives or exclusions, but the context strongly implies when this tool is appropriate.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns a temporary svix_url and mentions cost, but does not discuss side effects, reversibility, or permissions. It adds some useful context beyond the name, but not rich behavioral detail.

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

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

The description is concise with four sentences, each adding value: purpose, prerequisite, parameter guidance, return value, and cost. No redundant or unnecessary text.

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

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

The tool is simple (one optional param) and has an output schema. The description covers purpose, usage prerequisite, parameter behavior, and return value. It is largely complete, though it could elaborate on what 'temporary' means or clarify alternatives like create_svix_dashboard_url.

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

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

Schema coverage is 100%, and the schema's parameter description already includes the source (clerk.get_connected_accounts) and the default behavior. The tool description repeats this information without adding new meaning, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool creates a Svix app and associates it with a Clerk application for webhook delivery, using a specific verb and resource. It distinguishes itself from sibling tools like create_svix_dashboard_url and delete_svix_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 instructs to call clerk.get_connected_accounts first and explains how to target a specific connection via clerk_instance_id or use the default. It does not explicitly mention alternatives or exclusions, but provides clear contextual usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context: the URL is sensitive ('do not log or expose it'), grants access to webhook configuration, and is temporary. This goes beyond the basic schema and alerts the agent to handle the output carefully, though it does not mention details like expiration time or 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?

The description is four sentences long and every sentence earns its place: it states the purpose, warns about sensitivity, gives usage prerequisites, specifies the return value, and notes the token cost. It is front-loaded with the main verb and resource, making it easy to scan.

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 the absence of annotations, the description is complete enough for an agent to safely invoke the tool. It covers what is returned (svix_url), the prerequisite call, the optional parameter, and the sensitive nature of the output. The presence of an output schema reduces the need to describe the return format in detail.

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 clerk_instance_id with its origin (from get_connected_accounts) and default behavior (omit to use default). The description repeats this information, adding no new semantic detail. Since schema coverage is 100%, 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 uses a specific verb and resource: 'Generate a temporary URL for accessing the Svix management dashboard for a connected Clerk application.' This clearly states what the tool does and distinguishes it from other create token tools in the sibling list, such as clerk.create_actor_token or clerk.create_admin_portal_link_token, by focusing on the dashboard URL.

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 a clear prerequisite ('Call clerk.get_connected_accounts first') and explains how to choose the target connection ('Pass clerk_instance_id... or omit it to use the default account'). This gives actionable usage context, though it does not explicitly name alternative tools or state when not to use this tool, which would earn a 5.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the prerequisite call and connection targeting, but omits important behavioral details such as email verification requirements, duplicate email handling, password policy, or permission requirements. These gaps are significant for a create operation.

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

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

The description is three sentences, each adding distinct value: purpose, prerequisite/targeting, and cost. 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 5-parameter create tool with an output schema, the description covers purpose, prerequisite, and targeting logic. It does not explicitly mention potential error cases or uniqueness constraints, but the schema adequately covers parameter details, making the description 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 each parameter is already described. The description adds contextual value by explaining that clerk_instance_id comes from clerk.get_connected_accounts and that omitting it uses the default account, which augments the schema's basic 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 'Create a user in a connected Clerk application,' using a specific verb and resource. This distinguishes it from sibling create tools like create_email_address or create_invitations by focusing on the user object 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?

It explicitly instructs to call clerk.get_connected_accounts first and explains how to use clerk_instance_id to target a specific connection or default to the default account. This provides clear contextual usage, though it does not mention explicit alternatives or when not to use this tool.

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

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

With no annotations provided, the description carries the burden. It discloses the return behavior ('Returns the created or existing waitlist entries'), a prerequisite call, and a cost token amount. It does not mention side effects beyond adding, but for a simple creation tool this is reasonable. It also implies idempotency by returning existing entries.

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 four sentences, with the main action front-loaded and no padding. Each sentence earns its place: purpose, prerequisite/instance selection, return value, and cost. It is 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?

Given the low complexity (2 params, full schema descriptions, output schema present), the description covers all critical information: what it does, prerequisite, how to target an instance, return value, and cost. It lacks explicit alternatives but that is not essential for completeness here.

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 both parameters have detailed descriptions. The tool description only echoes the schema's guidance for clerk_instance_id and provides no new meaning for waitlist_entries beyond what the schema already states. Therefore, it adds no value beyond the baseline.

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

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

The description opens with a specific verb and resource: 'Add one or more email addresses to the waitlist in a connected Clerk application.' This clearly distinguishes the tool from sibling tools like list_waitlist_entries, invite_waitlist_entry, reject_waitlist_entry, and delete_waitlist_entry by focusing on creation/addition.

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 provides explicit usage guidance: 'Call clerk.get_connected_accounts first' and 'Pass clerk_instance_id to target a specific connection, or omit it to use the default account.' This gives clear context on prerequisites and parameter selection, though it does not explicitly name alternatives or when-not-to-use cases.

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

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

With no annotations provided, the description carries the full burden. It discloses the return type ('Returns a deleted confirmation') and the token cost (8 tokens). The word 'Remove' makes the destructive nature clear, and the prerequisite call provides useful behavioral context. It does not cover irreversibility or permissions, but for a simple identifier deletion, this is adequate.

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

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

The description is concise and front-loaded: purpose, prerequisite, parameter usage, return value, and cost are each covered in short, clear sentences. Every sentence provides distinct 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 that an output schema exists, the description need not explain return values beyond the confirmation statement. It covers the prerequisite connection step and optional parameter handling, which are important for correct use. The cost note adds completeness. Minor omission is lack of error behavior, but overall it is sufficient for a delete tool with fully described 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?

The input schema provides 100% coverage, with detailed descriptions for both identifier_id and clerk_instance_id. The description adds only a restatement of the clerk_instance_id usage ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account'), which is already present in the schema. No additional semantic depth is added.

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

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

The description begins with 'Remove an allowlist identifier by id,' which clearly states the action (remove) and the resource (allowlist identifier). This distinguishes it from sibling tools like delete_blocklist_identifier and create_allowlist_identifier.

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 a clear prerequisite: 'Call clerk.get_connected_accounts first.' It also explains the optional clerk_instance_id parameter with conditions for use and omission. While it does not explicitly mention alternatives or when not to use, the context is sufficient for correct invocation.

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

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

Since no annotations are provided, the description carries the burden. It discloses irreversibility ('Permanently delete'), the return payload ('Returns the deleted API key id and a deleted flag'), token cost, and a prerequisite dependency. It doesn't cover error handling or permissions but is more transparent than typical deletion tools.

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

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

The description is four succinct sentences, front-loaded with the main action, then prerequisites, return value, and cost. Every sentence is informative without any fluff or repetition.

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

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

For a simple delete operation with two parameters, the description adequately covers purpose, sequence, return value, and cost. It could mention revoke_api_key as an alternative for non-destructive operations, but the 'permanently' signal makes the tool's use case clear. Overall, it is complete for its complexity.

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

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

Schema description coverage is 100% and already documents both parameters well, including the optional behavior of clerk_instance_id. The description only restates what the schema provides ('or omit it to use the default account'), adding no extra semantic meaning beyond the schema.

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

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

The description opens with 'Permanently delete an API key from a connected Clerk application,' which is a specific verb+resource statement. It clearly distinguishes from sibling clerk.revoke_api_key via 'permanently,' signaling a destructive final action.

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

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

Provides explicit usage guidance: 'Call clerk.get_connected_accounts first' and explains how to use clerk_instance_id vs default account. Does not explicitly contrast with revoke_api_key, but the 'permanently' wording implies when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return ('Returns a deleted confirmation') and cost, but doesn't mention idempotency, error handling, or permission requirements. The deletion operation is simple, but a bit more behavioral context would be helpful; this is minimum viable.

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 four short sentences, with the primary action first, then usage guidance, return type, and cost. Every sentence serves a purpose with no fluff, making it highly readable and easily scannable.

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 (two params, both with schema descriptions) and the presence of an output schema, the description is largely complete. It adds the prerequisite call and cost information. A 4 is warranted because it's thorough enough for a straightforward delete operation, though it doesn't discuss error cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The added 'Call clerk.get_connected_accounts first' is a helpful prerequisite, but the description mostly repeats the schema's own language about clerk_instance_id. It doesn't add significant meaning beyond the schema, so 3 is appropriate.

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

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

The description opens with 'Remove a blocklist identifier by id,' which is a specific verb+resource+scope statement. It clearly distinguishes this from siblings like clerk.create_blocklist_identifier and clerk.delete_allowlist_identifier by naming the blocklist identifier as the target.

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 a clear prerequisite: 'Call clerk.get_connected_accounts first,' and explains when to pass or omit clerk_instance_id. It doesn't explicitly mention alternatives like delete_allowlist_identifier, but the context makes the use case obvious. Clear context without exclusions earns a 4.

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. It discloses that the tool removes a domain, describes the return value ('deleted domain id and a deleted flag'), and explains instance-targeting behavior. It also notes a 10-token cost. It does not explicitly state irreversibility, but given the clear 'Remove' verb and return flag, it is sufficiently transparent.

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 about four sentences, each serving a purpose: the core action, prerequisite/parameter guidance, return value, and cost. It is front-loaded and contains no 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?

This is a simple two-parameter tool with a good output schema. The description covers the prerequisite connection setup, optional parameter behavior, and expected return, making it complete for an agent to invoke 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 both parameters have descriptive details (domain_id format, clerk_instance_id source and default behavior). The description reinforces the clerk_instance_id guidance but adds little beyond the schema, so a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Remove a custom domain from a connected Clerk instance.' This clearly distinguishes it from sibling tools like clerk.delete_organization_domain, which targets organization domains, and domains.* tools that operate on domain registration.

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 user to 'Call clerk.get_connected_accounts first' and explains how to choose a target via clerk_instance_id or default to the default account. It gives clear contextual guidance for using the tool, though it does not mention alternatives 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 provided, so the description carries the full burden. It discloses the return behavior ('Returns the deleted email address summary when Clerk provides it') and includes cost information, but does not mention whether deletion is irreversible, requires specific permissions, or cascades to other data. Acceptable but not comprehensive for a destructive operation.

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

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

The description is four sentences with no wasted words. It front-loads the core action, then provides necessary context about connected accounts, return value, and cost. Every sentence contributes useful information.

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

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

For a simple 2-parameter delete tool, the description covers the main action, prerequisite, connection targeting, and return behavior. It does not explain edge cases like invalid IDs or permission requirements, but given the presence of an output schema and full parameter schema coverage, the essential context is 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 description coverage is 100%, so the schema already documents both parameters. The description reinforces the clerk_instance_id behavior by tying it to the prerequisite call, but adds minimal new meaning beyond what the schema provides. 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 ('Delete a Clerk email address by its id') and specifies the resource and required identifier. It distinguishes from sibling tools like create_email_address and update_email_address by focusing on deletion.

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

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

Provides explicit guidance to call clerk.get_connected_accounts first and explains how to handle the optional clerk_instance_id parameter. It gives a clear usage context but does not explicitly state when not to use this tool or mention alternatives.

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

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

With no annotations, the description carries full burden. It discloses the return value and the cost, but does not mention irreversibility, required permissions, error conditions, or side effects beyond 'Delete'. This adds some context but leaves important behavioral gaps.

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

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

The description is four sentences, each serving a clear purpose: purpose, usage instruction, return value, and cost. It is front-loaded with the core action, with no redundant or vague 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?

The description includes a prerequisite, parameter targeting instruction, return value disclosure, and cost. With an output schema present, return details are covered. However, it omits failure scenarios and permission requirements, which would make it more complete for a destructive 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% for both parameters, so the schema already defines connection_id and clerk_instance_id thoroughly. The description reinforces the instance id behavior with 'Pass clerk_instance_id to target a specific connection, or omit it to use the default account' but adds no substantial new meaning over the schema.

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

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

The description opens with 'Delete an enterprise SSO connection from a connected Clerk application', which is a specific verb+resource statement. It clearly distinguishes from sibling tools like get_enterprise_connection, update_enterprise_connection, and create_enterprise_connection.

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

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

Provides explicit prerequisite: 'Call clerk.get_connected_accounts first' and explains when to pass clerk_instance_id vs omit it to use the default account. This gives clear context for usage, though it does not explicitly name alternative tools or when-not-to-use scenarios.

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

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

With no annotations provided, the description carries the full burden. It discloses irreversibility ('This action is irreversible') and the return value ('Returns the deleted template id and a deleted flag'), which are key behavioral traits. It also implies the operation is scoped to a connected Clerk application. No contradictions with annotations exist.

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 four sentences, each adding value: purpose, prerequisite, irreversibility/return, and cost. It is front-loaded and contains no fluff or redundancy.

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

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

For a two-parameter delete tool with no annotations and an output schema, the description covers all necessary context: what it does, how to select the target, irreversibility, and the expected return. It does not need to explain error handling or return format further, as the output schema exists.

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 a bit of usage context for clerk_instance_id ('target a specific connection, or omit it to use the default account'), but this largely mirrors the schema description. No significant additional meaning is provided for template_id beyond the schema's mention of retrieve/update/delete.

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

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

The description states a specific verb ('Permanently delete') and resource ('JWT template'), clearly distinguishing it from sibling tools like update_jwt_template or create_jwt_template. The 'permanently' qualifier adds important scope beyond a generic delete.

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

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

Provides clear prerequisite guidance ('Call clerk.get_connected_accounts first') and clarifies how to target a connection (pass clerk_instance_id or omit for default). It does not explicitly mention alternatives or state when not to use this tool, but the context is sufficient for an agent to invoke it correctly.

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

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

With no annotations provided, the description carries full burden. It discloses the return ('Returns a deletion confirmation') and cost ('Cost = 10 tokens'), but does not mention side effects, error behavior, or permission requirements beyond the obvious destructive nature of deletion.

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 four short sentences: purpose, prerequisite/account selection, return value, and cost. It is front-loaded and every sentence earns its place with no redundancy.

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

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

For a simple 2-param deletion tool with an output schema, the description covers purpose, prerequisite, account targeting, return behavior, and cost. It lacks explicit alternatives and error handling, but is generally sufficient for basic 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% with clear descriptions for both machine_id and clerk_instance_id. The description adds the account-targeting behavior ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account'), but this is already in the schema, so no significant 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 'Delete a machine by id from a connected Clerk instance', using a specific verb (delete) and resource (machine) with context (connected Clerk instance). It distinguishes from sibling delete tools like delete_machine_scope and delete_domain by exactly naming the resource.

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

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

The description provides a clear prerequisite ('Call clerk.get_connected_accounts first') and explains how to target a specific connection with clerk_instance_id or use the default account. It lacks explicit alternatives or exclusions, but the context is sufficient for basic usage.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states the effect (removing access) and that it returns a deletion confirmation, but it does not mention whether the action is irreversible, what side effects occur, or any authentication requirements. For a delete command, this is adequate but not fully transparent about consequences.

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 short sentences, front-loaded with the main purpose. Every sentence earns its place: the action, the prerequisite, the optional parameter behavior, and the return type. No 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 output schema exists, the description does not need to detail the return object. It covers the prerequisite, parameter selection, and the outcome (deletion confirmation). It lacks mention of error conditions or edge cases, but for a straightforward delete operation this is sufficient 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?

Schema description coverage is 100%, giving baseline 3. The description adds valuable guidance beyond the schema, particularly about calling clerk.get_connected_accounts first and how to use clerk_instance_id to target a specific connection or omit it for the default. This clarifies the exact use of parameters beyond their raw definitions.

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

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

The description clearly states the tool's function: 'Delete a machine scope, removing access from one machine to another.' This uses a specific verb (delete) and resource (machine scope), and distinguishes it from siblings like delete_machine (deletes the machine itself) and create_machine_scope (creates a scope).

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

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

The description provides explicit usage context: 'Call clerk.get_connected_accounts first' and explains how to select an instance with clerk_instance_id or omit it for the default account. It does not explicitly mention alternative tools for similar operations, but the primary usage guidance is clear and actionable.

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

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

With no annotations provided, the description carries the full burden. It discloses that the operation is a permanent deletion, states the action's return value ('Returns the deleted OAuth application object'), and notes the token cost. This goes beyond a bare 'delete' statement and helps the agent understand the irreversible and returning nature of the call.

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

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

The description is compact and front-loaded with the primary purpose. Each sentence adds useful information: the operation, prerequisite and targeting instructions, return value, and cost. No filler or repetition of schema details, making it efficiently structured.

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

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

For a destructive delete tool with two parameters and an output schema, the description covers the essential context: prerequisite call, targeting selector, return value, and cost. It does not detail error scenarios or explicit authorization requirements, but the permanent-deletion warning and return behavior are sufficiently complete 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 with clear parameter descriptions (e.g., clerk_instance_id has default null and explanation, oauth_application_id is required with 'oa_...' format). The description adds minimal new semantics beyond restating the targeting behavior already present in the schema, so a 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 opens with 'Permanently delete an OAuth application from a connected Clerk application,' which uses a specific verb ('delete'), specifies the resource ('OAuth application'), and adds 'permanently' to convey irreversibility. It clearly distinguishes this from sibling tools like update, get, list, or create OAuth applications.

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

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

The description provides clear usage context: it tells the agent to call clerk.get_connected_accounts first and explains how to target a specific connection via clerk_instance_id or fall back to the default account. While it doesn't explicitly mention alternatives or when-not-to-use, the instructions give actionable prerequisites and targeting guidance.

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

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

With no annotations, the description carries the full burden. It transparently discloses that the action is irreversible, states the return value (deleted organization id and deleted flag), and even notes the token cost. It doesn't mention cascade effects on related data, but it adequately covers the most critical safety aspect.

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 four concise, purposeful sentences: purpose, prerequisite/parameter routing, irreversibility/return, and cost. Each sentence earns its place, with the main purpose front-loaded and no redundant 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 modest complexity (2 params, 1 required, output schema present), the description covers all essential aspects: purpose, prerequisite workflow, parameter semantics, safety warning, return value, and cost. It is complete 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?

Schema coverage is 100% for both parameters, but the description adds operational meaning beyond the schema by instructing to call clerk.get_connected_accounts first and clarifying the behavior when clerk_instance_id is omitted. This contextual workflow 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 states 'Permanently delete an organization from a connected Clerk application' with a specific verb, resource, and scope. It clearly distinguishes this tool from sibling deletion tools like delete_organization_domain or delete_organization_membership by targeting the organization 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?

It provides explicit usage guidance: 'Call clerk.get_connected_accounts first' and explains when to pass clerk_instance_id vs omit it for the default account. It gives clear context and prerequisites, though it does not mention explicit alternatives 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?

With no annotations, the description carries the full burden for behavioral disclosure. It adds the return value (deleted domain id and deleted flag) and the prerequisite call, but does not mention whether deletion is permanent or any permission requirements, 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 brief and front-loaded with the purpose, followed by a prerequisite, parameter guidance, return value, and cost in a logical order. 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 tool's simplicity (2 parameters, output schema present), the description covers the essential operational steps, including the prerequisite call and return information. However, it omits any caveats (e.g., irreversible action or error handling), so it's not fully 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 schema covers both parameters, so the baseline is 3. The description adds meaning by explaining how to choose clerk_instance_id based on the connected account, which goes beyond the schema's default 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 uses the specific verb 'Remove' and names the exact resource ('organization domain from a Clerk organization'), clearly distinguishing it from other domain-related tools like clerk.delete_domain. It directly states what the tool does in the first sentence.

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

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

It explicitly instructs the user to call clerk.get_connected_accounts first and explains when to pass clerk_instance_id ('to target a specific connection') or omit it ('to use the default account'). This provides clear when-to-use guidance relative to connected account handling.

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 behavioral burden. It discloses irreversibility ('This action cannot be undone'), a cost ('Cost = 8 tokens'), and a dependency on clerk.get_connected_accounts. This goes beyond the bare action, though it does not detail permission requirements or side effects like removal of associated invitations.

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

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

Four short sentences, each earning its place: purpose, prerequisite/dependency, warning, and cost. The description is front-loaded with the main action and contains no redundant phrases 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 delete operation with full schema coverage and an output schema, the description adequately covers purpose, prerequisite, irreversibility, and cost. It does not address edge cases (e.g., removing the last admin), but that is not expected for this scope.

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 three parameters are clearly described. The description reinforces clerk_instance_id usage ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account') but adds no new parameter meaning beyond what the schema already provides.

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

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

The description opens with 'Remove a user from a Clerk organization,' which clearly states a specific action and resource. This distinguishes it from sibling tools like create_organization_membership and list_organization_memberships, leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage context: 'Call clerk.get_connected_accounts first' and explains how to target a specific connection versus the default. However, it does not explicitly contrast this tool with alternatives like create_organization_membership or update_organization_membership, so it lacks explicit exclusion guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the return payload, cost in tokens, and the prerequisite of connected accounts. It does not explicitly mention irreversibility, but 'delete' implies destruction, so this is reasonable.

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 four concise sentences: purpose, prerequisite, return value, and cost. It is front-loaded with the core action and includes no fluff, making it highly efficient.

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

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

Given the presence of an output schema and clear prerequisite instructions, the description is fairly complete. It could mention potential errors or that the permission must already exist, but for a simple delete tool it covers the essential operational 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% with descriptive parameter details, so the baseline is 3. The description adds little beyond repeating the clerk_instance_id guidance already present in the schema, such as 'Pass clerk_instance_id to target a specific connection.' It does not enrich parameter meaning meaningfully.

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 'Delete an organization permission from a connected Clerk application' with a specific verb and resource, clearly distinguishing it from sibling tools like delete_organization_role or delete_organization_membership. This is precise and unambiguous.

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

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

It provides explicit usage context by instructing to call clerk.get_connected_accounts first and how to target a specific connection via clerk_instance_id. However, it does not explicitly differentiate from alternative delete tools or state when not to use it, though the purpose itself makes this 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?

No annotations are provided, so the description carries the full burden. It discloses the return payload and cost, and implies a connection requirement via 'connected Clerk application' and the get_connected_accounts prerequisite. However, it does not explicitly state that deletion is irreversible or warn about potential side effects on members or other resources, leaving room for more 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 four short sentences covering purpose, prerequisite, targeting, return value, and cost. Every sentence adds value, and it is front-loaded with the action with no redundant or fluff 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?

For a delete tool with one required parameter, high schema coverage, and an output schema, the description sufficiently covers purpose, prerequisite, targeting, return, and cost. It could add explicit notes on irreversibility or error cases, but given the simplicity, it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents both role_id and clerk_instance_id. The description reiterates the omit-to-use-default behavior for clerk_instance_id and adds the get_connected_accounts prerequisite, but it does not add significant meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool deletes an organization role from a connected Clerk application. The verb 'delete' and resource 'organization role' are specific, and this distinguishes it from sibling tools like update_organization_role or create_organization_role.

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 by instructing to call clerk.get_connected_accounts first and explains how to target a specific connection via clerk_instance_id or omit it for the default account. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it states the action is irreversible, returns a deleted confirmation, and discloses the token cost. This covers key behavioral traits, though it could mention error handling or side effects, but those are less critical for a delete operation.

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

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

The description is tight: action, prerequisite, targeting, irreversibility/return, and cost—all in four short lines. No filler or repeated information; 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 simplicity of the tool (2 params, 100% schema coverage, output schema present), the description covers everything essential: the operation, prerequisite, instance targeting, irreversibility, and cost. Return values are handled by the output schema, so no further detail 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 100%, so a baseline of 3 is appropriate. The description repeats the instance selection logic that the schema already documents, adding no substantial new parameter meaning. The extra guidance about calling get_connected_accounts is more of a usage guideline than 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 opens with 'Delete a Clerk phone number by id', a specific verb and resource that clearly distinguishes it from the many other delete_* tools in the sibling list. There is no ambiguity about what this tool does.

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

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

It gives a clear prerequisite, 'Call clerk.get_connected_accounts first', and explains how to target a specific instance or default account with clerk_instance_id. It does not explicitly mention when not to use it or name alternatives, but the usage context is well established.

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 states the return value (deleted redirect URL id and deleted flag) and cost (10 tokens), and implies destructive action. However, with no annotations, it lacks explicit warnings about permanence or required permissions.

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

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

Four short, front-loaded sentences. No redundancy; each sentence adds meaningful information (action, prerequisite, optional parameter, return, cost).

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 2-parameter delete with output schema, the description covers usage, prerequisites, and return. It could mention that deletion is irreversible, but overall it's 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 coverage is 100%, so parameters are already described. The description reinforces the clerk_instance_id usage but doesn't add new format or constraints beyond the schema.

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

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

The description opens with a clear action: 'Remove an allowed redirect URL from a connected Clerk instance.' This specifies the verb, resource, and context, distinguishing it from related tools like clerk.create_redirect_url and clerk.get_redirect_url.

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

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

It explicitly instructs to call clerk.get_connected_accounts first and explains how to target a specific connection via clerk_instance_id or default. This provides clear context, though it doesn't mention alternatives 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. It discloses the side effect ('disassociate webhook delivery'), the return value ('deleted confirmation'), and the cost (10 tokens). It does not explicitly state irreversibility or permission requirements, but delete semantics and side effects are communicated. This exceeds the minimum.

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 purposeful: purpose first, then usage, then return/cost. No wasteful words. The cost is included, which is useful operational trivia. Highly concise and front-loaded.

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

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

For a destructive tool with one optional parameter and an output schema, the description covers purpose, prerequisite, parameter behavior, return type, and cost. It could more explicitly mention irreversibility or consequences of disassociating webhook delivery, but the given context is sufficient for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the schema's parameter guidance ('Pass clerk_instance_id to target a specific connection, or omit it to use the default account') and adds the prerequisite call. This is helpful but does not significantly go beyond the schema's own 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: 'Delete the Svix app associated with a connected Clerk application and disassociate webhook delivery.' This uses a specific verb and resource, and it distinguishes the tool from siblings like create_svix_app and create_svix_dashboard_url.

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 provides explicit prerequisite guidance: 'Call clerk.get_connected_accounts first.' It also explains how to target a specific connection vs. the default account. It does not explicitly name alternatives or exclusions, but the context is clear and actionable.

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