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.