SignupBouncer

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

The description adds substantial behavior beyond the annotations: it explains the verdict values, score range, reason codes, inbox normalization, typo suggestions, live mail-server lookup, and that all reasons are returned even if paid-plan-only. It also discloses caching and rate-limit storage practices in detail, which is valuable context for a privacy-sensitive validation tool.

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

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

The description is front-loaded with the core purpose and return behavior, then moves into lookup, privacy, caching, and rate-limit details. It is information-dense and mostly earns its length, though the final sentences about hashed storage are quite detailed and could be tightened slightly.

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, privacy implications, and existing output schema, the description is highly complete. It explains what is checked, what is returned, how normalization and typo suggestions work, and what is stored or cached, leaving an agent well equipped to use the tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema. The description adds meaning by clarifying that the email is normalized with Gmail dots and +tags folded, that the optional IP is the signup IP, and that the IP's network is returned, going 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 that this tool checks one email address, optionally with a signup IP, and returns a SignupBouncer-style verdict. It is specific about the resource and operation, though it does not explicitly differentiate itself from sibling tools such as lookup_burner_domain or explain_reason.

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

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

Usage is implied through phrases like 'the way SignupBouncer checks a new signup' and 'the signup's IP address,' which suggests this is for signup validation. However, there is no explicit when-to-use guidance, no exclusions, and no direct routing to sibling tools for related tasks.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuine behavioral value by disclosing the shape of the answer (points added, block-alone status, minimum plan tier), which the agent cannot infer from annotations. It does not discuss formatting or edge cases for unknown codes, keeping it below 5.

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

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

Two tight sentences, front-loaded with the core action, then the argument and the no-argument fallback. No filler; every clause carries 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the fields the agent will receive. Combined with full schema coverage on the single parameter and complete annotations, nothing needed to invoke or interpret the tool is missing.

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

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

With one parameter at 100% schema coverage, the baseline is 3, but the description adds value by naming concrete example codes (disposable_domain, burner_mx, repeat_inbox, datacenter_ip) that illustrate the expected value domain, and reiterates the omit-to-list-all behavior meaningfully. It does not specify validation or error behavior for invalid codes.

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 (Explains) plus a specific resource (a SignupBouncer reason code), and enumerates the exact facts returned: meaning, point weight, whether it blocks alone, and lowest plan. This is clearly distinguishable from siblings like check_email and lookup_burner_domain, which perform lookups rather than explain codes.

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 defines the two operating modes: pass a code to explain one, or omit it to list every code. That covers the main branch an agent must decide. It stops short of contrasting against siblings (e.g. when to call lookup_burner_domain instead), so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint/idempotentHint and that this is a closed-world read. The description adds value beyond them by disclosing the auth requirement ("Needs an API key") and describing the shape of what comes back. It does not contradict any 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?

Front-loads the prerequisite and the return-content inventory, and the key-scoping rule is placed last where it belongs. The field enumeration is long but every clause carries distinct information, so it stays dense rather than padded.

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

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

With no output schema, the description does the heavy lifting by enumerating the returned settings groups (rules + context/plan/check values). An auth caveat and the param-scoping rule are both present. Only a note on the sibling mutation tool is missing.

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

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

Schema description coverage is 100% and the single 'app' parameter is fully documented in the schema, including the identical key-scoping rule. The description restates rather than extends this, so the baseline 3 applies.

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

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

"Returns the Rules settings of one of your apps" names a specific verb and resource, then enumerates exactly what those settings contain (mode, score cutoffs, hook behavior, refusal message, velocity thresholds). This lets an agent separate it from update_rules and explain_reason without opening any schema.

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?

States the API-key prerequisite and gives concrete when-to-omit guidance for the app parameter ("A key made for one app reads that app, so leave out 'app'. An older all-apps key needs 'app'"). It does not explicitly name update_rules as the mutation counterpart, so routing between read and write is only implied.

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

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

Adds real behavioral context beyond the readOnly/idempotent/closed-world annotations: the API key is read from SIGNUPBOUNCER_API_KEY, the call has a 1.5-second limit, and any failure fails open so the signup proceeds. These are exactly the operational facts an agent needs and cannot infer from annotations.

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

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

Three sentences, front-loaded with the return value, then usage trigger, then runtime constraints. The stack enumeration is long but earns its place because the list is the tool's core coverage contract.

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?

An output schema exists, so return shape need not be explained. The description still covers which stacks are supported, when to invoke it, and the timeout/fail-open behavior, leaving no meaningful gap for a single-enum-parameter 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% with an enum, so the baseline is 3; the description goes further by noting that supabase and ory need no code (hook-based) while the remaining stacks are code samples. It adds per-option semantics beyond the bare enum list, though not full detail for each stack.

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+resource ('Returns the steps and the copy-paste code that checks new signups') and enumerates the exact stacks covered, so the agent knows precisely what artifact comes back. It is inherently distinguishable from the sibling check_email/explain_reason tools, which evaluate emails rather than emit integration code.

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 a clear trigger condition: 'Use it when the user is building or changing a signup, register or auth flow.' That is strong positive guidance, but it names no alternative or exclusion (e.g., using check_email for a one-off email check), so routing is left partly to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, and the description still adds meaningful behavior: it operates only on loaded lists with no DNS lookup, and discloses the resulting gap that check_email covers. This is genuine context beyond structured fields, though pagination/volume behavior is not mentioned.

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

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

Purpose and classification categories are front-loaded, and the operational limitation and alternative follow logically. It is dense and somewhat run-on, packing enumerations into long clauses, but little is wasted.

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

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

With no output schema, the description carries the burden of explaining return semantics and does so by enumerating result categories plus the harvester observation timestamp. It leaves the exact result format unspecified, but the agent has enough to invoke and interpret it.

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 single parameter's schema already documents that it accepts a domain or an email address. The description's 'Accepts a domain or an email address' merely restates the schema, so the baseline 3 applies with no added syntax or format detail.

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 (look up / says whether) against a specific resource (a domain on SignupBouncer's burner/relay/free-subdomain lists). It explicitly enumerates the classification outcomes and separates itself from check_email for the case of brand-new burner domains.

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

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

Names a sibling (check_email) and the condition under which that sibling is required: brand-new burner domains on a burner mail server. It gives clear context for when this lookup suffices, though it doesn't cover other sibling boundaries such as get_rules or explain_reason.

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

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

Annotations already flag this as a destructive, idempotent write, and the description adds real behavioral context beyond them: the change takes effect on live traffic, updates are partial ("Send only the settings to change. The others stay as they are"), validation is atomic ("If one value is wrong, nothing changes and the answer says which"), settings including block_message persist until changed or the app is removed, and the response returns the post-change rules. It stops short of saying whether the change is reversible or how to undo it, so it sits just under the top mark.

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 API-key prerequisite and the core effect are front-loaded well, but the middle is a string of short choppy sentences that repeat ground already covered by the schema (mode enforce/shadow, the app-id key rule). It is informative but could be tightened without losing substance.

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 9-parameter, nested-object, destructive write with no output schema, the description covers authentication, partial-update semantics, live effect, atomic failure mode, return value and persistence. An agent has everything needed to call it safely and correctly.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds meaning the schema does not: what enforce vs shadow actually do to real signups, that untouched settings are preserved and that block_message text persists across calls. It does not explain the checks or velocity knobs at all, leaving those entirely to the schema.

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

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

The description states a specific verb and resource ("Changes the Rules settings of one of your apps") and immediately names the observable consequence — live signup blocking changes and the next real signups are scored under the new settings. That effect plus the note that it "Returns the app's rules afterwards" clearly separates it from the read-only sibling get_rules.

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 strong operational guidance: confirm with the user first, send only the settings to change, and how to pick the key (per-app key omits "app", older all-apps key requires it). It states when to use it (to change rules) but never explicitly names get_rules as the read-only alternative, so the alternative-selection guidance is implicit rather than stated.

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