Enforcer

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds 'public bootstrap' framing, clarifies that the returned privy_app_id is never a secret, and warns that tenant_code is a join secret that must be kept out of logs and customer-visible channels. This is beyond-annotation context about data sensitivity.

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

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

Three sentences, each earning its place: purpose/return summary, when-to-call with sibling mention, and security handling for the sensitive parameter. No redundancy or filler; front-loaded and easy to parse.

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

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

Great completeness for a low-complexity tool: covers purpose, auth-scheme return summary, follow-up call relationship, and privacy-sensitive parameter handling. The only gaps are that response_format/concise default behavior is left to the schema (but the schema documents it fully) and it does not clarify that tenant_code is unpublished across the schema's '0 required' signals. Still, an agent can call it correctly with this description.

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 one extra nuance: tenant_code is a 'join secret' that should not be logged, which is not in the schema. It does not add explanatory meaning for response_format beyond the schema's own concise vs. detailed description, so the net increment is modest.

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

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

States a clear verb+resource: returns a tenant's login UI bootstrap configuration. It names the specific payload (auth scheme type and public privy_app_id) and explicitly distinguishes itself from getSiweNonce by naming the sibling. An agent can tell exactly what this tool provides.

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 an explicit when-to-call instruction: 'Call this before getSiweNonce when you do not already know the tenant's auth scheme.' It also gives a sensitive-handling rule for tenant_code (do not log or echo). Alternative siblings are identifiable even though only one is named.

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

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

Annotations already convey non-read-only and idempotent=false, but the description adds meaningful behavior: the nonce is single-use, not a credential, and tenant_code must not be logged. The upfront 'Public' declaration also matches the openWorldHint annotation.

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

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

The description uses four tight sentences, each earning its place: purpose, usage flow, authorization pattern, and security warnings. No filler, and the core purpose is front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, the sign-in flow, optionality of tenant_code, and sensitive-data handling. It does omit response format or expiry behavior, but those are minor for issuing a nonce.

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 only describes body as a JSON object with wallet_address and tenant_code, but the description adds that wallet_address is the target and tenant_code is optional scoping. It also provides a security-relevant warning about tenant_code. It stops short of specifying the wallet_address format.

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: 'issue a single-use SIWE nonce for wallet_address' and clearly ties it to the EIP-4361 wallet sign-in flow. It also distinguishes itself from sibling auth tools by calling out the dedicated SIWE agent auth pattern.

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

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

The description gives a clear usage flow: embed the nonce in an EIP-4361 message, sign it, then call login with provider: siwe. It explains this is how an agent signs in without raw HTTP, but it does not explicitly enumerate when to avoid sibling tools like getAuthConfig or requestOtp.

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

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

Annotations only provide coarse flags (openWorldHint true, readOnlyHint false), so the description carries the behavioral burden. It discloses an unusual behavioral trait: the server does not adopt the minted tokens as the session credential and they must be returned to the operator. The explicit no-logging and no-repeating rules add security-relevant behavior beyond the annotations.

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

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

Every sentence earns its place: purpose, provider strategy, exclusions, token handling, and security constraints. The description is dense but not bloated, and the most important routing information is front-loaded.

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

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

For a multi-provider auth tool with no output schema, the description covers the provider matrix, prerequisite tools, security handling, and operator handoff well. It does not describe exact response fields, error cases, or when to prefer refreshToken, but these are secondary to the core login flow.

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 value by mapping providers to their required parameter combinations: siwe uses message+signature, email_otp uses email+otp, and phone_otp uses phone+otp. It also identifies the source tools for those credentials, which the bare schema properties do not provide.

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: 'Authenticate and receive an access/refresh token pair.' It also enumerates accepted providers and explicitly excludes browser ceremonies, so an agent can tell what login produces and what it is not.

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 concrete when-to-use guidance: siwe is 'preferred for dedicated agents that can sign', while email_otp and phone_otp are tied to their prerequisite tools. It also states what not to use (Passkey, Privy, SSO) and what to do with the result. It does not contrast login with the sibling refreshToken, but the core selection guidance is explicit.

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

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

The description discloses key behavioral traits beyond the annotations: the server does not adopt the new pair as the session credential, reuse revokes the family, and 409 is benign. This adds significant context about side effects and retry semantics that annotations alone do not convey. No contradiction with annotations.

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

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

The description is compact and front-loaded: it states the core action first, then error semantics, then a security warning. Every sentence earns its place, and there is no redundant repetition of schema or annotation information.

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

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

For a single-parameter tool with no output schema, the description covers the essential context: what the tool does, how to handle errors, side effects, and security precautions. An agent has enough information to invoke it correctly and interpret failures.

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 only parameter (refresh_token) is self-explanatory. The description adds context about the token's role and error behavior, but the parameter itself is already clear from the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Exchange') and resource ('a refresh_token for a new access/refresh pair'), clearly distinguishing it from sibling auth tools like login or getSiweNonce. It also names the exact error conditions, making the tool's purpose unambiguous.

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

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

The description explicitly explains when to use the tool (to exchange a refresh token) and provides critical guidance on handling errors: 401 means the token was reused and the family is revoked, while 409 refresh_raced is benign and should be retried with the latest stored token. It also warns against logging tokens, which is a clear operational guideline.

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

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

The description adds behavioral context beyond annotations: it clarifies idempotency ('or idempotently return'), states that no tokens are issued (critical), and provides security constraints. Annotations are minimal (readOnlyHint false, etc.), so the description carries the burden well, though it doesn't detail side effects 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 concise and front-loaded with the primary purpose. It packs a lot of information in three sentences without redundancy. Every sentence adds value, including security warnings.

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 (one nested object with multiple optional parameters) and no output schema, the description covers the essentials: which parameters are needed per provider, idempotency, token issuance, and security. It could detail what the response looks like, but that's minor. It's complete enough for an agent to call 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 description coverage is 100%, so the schema already documents all parameters. The description adds some value by summarizing provider-specific requirements and security notes, but it doesn't go far beyond the schema's own descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates or idempotently returns an account, which is a specific verb+resource. It differentiates from login by explicitly saying it does not issue tokens and that login should be called afterwards. However, it doesn't explicitly name the sibling 'login' in the same sentence, though it is clear from context.

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

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

The description provides explicit when-to-use guidance: it says to call login afterwards for signing in, and it lists which providers are supported, explicitly excluding Passkey/Privy/SSO as out of agent surface. It also gives security guidelines about not logging sensitive data.

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

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

Annotations already convey a non-read, non-idempotent external action, but the description adds important behavior: always returns 200 on success, may return dev_otp in dev deployments, and warns to treat codes as secrets. It could mention failure or rate-limit behavior, but the added context is substantial.

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

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

Packs purpose, response shape, dev-mode caveat, follow-up call, and security warnings into a compact block with the key behavior front-loaded. No filler.

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

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

For a tool with no output schema, it covers the success response, special dev_otp response, follow-on login call, and security constraints. It does not describe error responses, but the essential calling 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?

The schema only describes the body container, so the description adds real meaning: email is the recipient and tenant_code optionally scopes the request. It does not fully define tenant_code semantics, but it compensates for the sparse 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?

States a specific verb and resource: emails a one-time login/registration code to an email address. It is clearly distinguished from sibling requestSms by channel and from login/register by its role in the flow.

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 says it is intended for harnesses that cannot SIWE, names SIWE as the preferred dedicated-agent path, and directs the agent to call login with email_otp afterward. This gives a concrete when-to-use and next-step.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, but description adds critical behavior: initiates external SMS challenge, is intentional for harnesses, and gives security warnings (do not log code, do not paste OTP). This is essential context beyond annotations.

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

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

Concise, front-loaded with action and scope, then error conditions, then next steps, then warnings. Every sentence adds value; zero 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?

Despite no output schema, description fully covers error conditions, next step, alternatives, and sensitive data handling. An agent can successfully invoke and follow up.

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 has 100% coverage with both parameters described (phone, tenant_code as part of request body). Description does not re-explain them, but adds the 'scoped by tenant_code' meaning, which is slightly beyond schema. Baseline 3 is appropriate.

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

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

Clear verb 'start' with resource 'Twilio Verify SMS login challenge' to 'phone', scoped by tenant_code. Distinguishes from siblings like requestOtp and login.

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

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

Explicit next step (call login with provider phone_otp), error conditions (400 if not configured/rate-limited), and mentions SIWE as preferred alternative. Perfect when-to-use guidance.

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