Reveal App Token

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

Beyond the readOnly/idempotent annotations, the description discloses that this tool is deliberately the only one returning appToken, that output enters the model's context and client logs, and that the App Secret is never exposed. It also gives the exact return shape, auth expectations, and a full error list. These facts materially change how an agent should invoke and handle results, and they are not captured by 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 long but every sentence carries essential information: purpose, redaction policy, App Secret caveat, requirements, auth, errors. It is front-loaded with the core action and organized into clear labeled segments, achieving high density without 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?

With no output schema, the description compensates by specifying the exact return shape ({ appId, appToken, note }), prerequisites, authentication model, error cases, and security context. For a credential-revealing tool, this is unusually complete; an agent has everything needed to decide when to call it and what to expect.

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

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

Schema description coverage is 100%, so the parameters are already fully documented: appId is a 24-char hex ID defaulting to the selected app, and confirm must be true to acknowledge the token will appear in conversation. The description reinforces the confirm requirement and ownership precondition but adds no new parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description immediately states the exact action and target: 'Reveal the appToken of an app the caller owns, for a chat-component snippet or a widget config.' It further differentiates from all other tools by noting they redact appToken/appSecret/tenantSecret, while this tool returns exactly { appId, appToken, note }. This makes the tool's unique role unmistakable.

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 frames the intended use case ('for a chat-component snippet or a widget config') and requires ownership of an app via `ethora-app-create` or `ethora-app-list`. It also directs alternatives clearly: backend integrations should use revocable server tokens, and the App Secret is never returned over MCP. This is explicit when-to-use and when-not-to-use guidance, including a named alternative.

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