ethora-mcp-server

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

Beyond the annotations, the description reveals important side effects: lazy creation of a per-App BotInstance user with isBot:true, live XMPP client spawning, and no required ai-service restart. This is exactly the kind of behavioral context an agent needs for a mutating, side-effectful 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 compact, front-loaded with the primary action, and every sentence earns its place by adding behavioral or usage detail. No filler or redundant restatement of the tool name.

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?

Together with the fully described schema and annotations, the description provides enough context for an agent to invoke the tool correctly: the action, the per-agent call pattern, the lazy creation side effect, and the operational consequence. The lack of an output schema does not hurt this side-effect-focused 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%, so the parameter descriptions already carry the semantic weight. The tool description adds a useful 'once per agent' and 'per-App' framing, but it does not materially extend what the schema already states about parameters.

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 ('Invite') and resource ('Agent into a chat room'), immediately clarifying what the tool does. It further distinguishes the operation from sibling agent-CRUD tools by describing an invitation/membership action with multi-agent behavior.

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 concrete usage context: call once per agent, multiple agents can coexist, and points to the quickstart prompt for the full multi-agent recipe. It does not explicitly name excluded alternatives, but the usage context is clear enough for an agent to decide when to invoke 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?

Beyond annotations, the description discloses that this mutates app state, which route is used under user auth versus app-token fallback, required ownership, and likely 404/403 errors. It also surfaces the precondition that a bot instance must already exist, which is critical behavioral context the annotations do not provide.

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 dense but efficiently organized: main effect, required precondition, auth behavior, errors, and related tools. Every sentence adds actionable information with 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 mutating activation tool with no output schema, the description covers purpose, preconditions, auth, errors, and related follow-ups. It does not describe the response/return value, but for this tool the key information an agent needs before invoking it 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 baseline is 3. The schema already explains each parameter's default, source, and the API-created vs dashboard-created app distinction. The description adds some relational context (activating sets `App.defaultBotInstanceId`) but does not substantially extend what the schema already communicates.

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: 'Make an agent the app's ACTIVE widget bot' and names the exact effect (`App.defaultBotInstanceId`, `botStatus: on`). It clearly explains why this matters (`POST /v2/widget/sessions`) and distinguishes this activation action from general bot-enable or agent-update 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 gives strong context for when to use the tool: it is 'Required before an embedded widget can answer on an API-created app' and states the precondition to invite the agent first. It also lists related next steps (`ethora-widget-embed-snippet`, `ethora-bot-instances-list`). It does not explicitly state when not to use it, but the context is clear enough.

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 non-idempotent behavior, and the description adds valuable side effects: the source agent is unchanged and the new clone becomes the session's current agent context. It also discloses auth mode and specific error outcomes, going beyond the structured fields.

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: action and route first, then side effects, auth prerequisite, and error cases. Every sentence carries useful information with 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 single-required-param mutation, the description supplies the route, side-effect behavior, auth prerequisite, and error semantics. Although there is no output schema, the information provided is sufficient for an agent to invoke 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 documents all four parameters at 100% coverage, so the baseline is 3. The description adds context that name/slug/summary are optional overrides and that the source agent remains unchanged, but it does not need to repeat parameter-level details.

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 'Duplicate an existing saved agent into a new agent' – a specific verb and resource, then adds optional overrides and the exact route. It clearly distinguishes cloning from creating or updating by noting the source agent is unchanged and the clone becomes the current agent 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?

Auth requirements are explicit ('app-token mode after ethora-app-select + ethora-auth-use-app'), and error conditions are mapped to 401/403/404/422. It does not explicitly compare against create/update alternatives, but the context makes the intended use 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?

Annotations already indicate a write operation (readOnlyHint=false), and the description adds valuable behavioral details: auth mode restrictions, the response-gate mechanism, damping factors for cooldownSec and responseProbability, and the multi-agent turn-handoff pattern. These go beyond the annotations and schema, providing the agent with crucial 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?

Three sentences, front-loaded with the core action and endpoint, then key constraints, then multi-agent usage. Every sentence adds value with no fluff. The structure is logical and 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?

For a tool with 19 parameters and no output schema, the description covers the essential context: what the agent is, auth modes, the multi-agent recipe, and pointers to a quickstart. It doesn't list every parameter (that's the schema's role) but provides the high-level understanding an agent needs 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds extra meaning beyond the schema: it explains the multi-agent workflow, mentions the response-gate settings as a group, and clarifies auth mode limitations. It doesn't detail every parameter but adds meaningful usage context that isn't in the schema. This lifts it above 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 action 'Create a reusable AI agent' with the specific endpoint (POST /v2/apps/:appId/agents). It distinguishes from siblings like update, delete, clone, and invite-to-chat by explaining that this creates the persona, while others handle subsequent steps. The purpose is unambiguous and well-differentiated.

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 states when to use this tool (create agents) and how to use it in multi-agent scenarios: create each agent separately then invite them to a chat. It also specifies auth mode constraints (user/B2B accepted, app-token not accepted) and points to a quickstart recipe. This is clear guidance on when and how to invoke the 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?

Annotations already declare destructiveHint=true, and the description adds meaningful behavioral detail beyond that: it removes BotInstances as well as the Agent, and requires an environment variable gate. This gives an agent a clear picture of the side effects and invocation prerequisites. It does not contradict the annotations, and it enriches the safety profile with specific 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 two sentences with no filler. The core action and endpoint lead, followed by the destructive consequence and the gating condition. Every sentence earns its place and the structure is easily scannable for an agent.

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 single-parameter delete tool, the description is complete: it names the action, endpoint, affected resources, and enabling condition. The schema covers the parameter format, and annotations cover safety flags. No output schema exists, but explaining return values is not essential for a delete operation with this level of transparency.

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 parameter 'agentIdOrAddress' is already well-documented in the schema as a Mongo _id or EOA-style address. The description adds no additional parameter-level meaning, but with full schema coverage the baseline score of 3 is appropriate. No extra clarification is necessary here.

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 clearly states the tool's action: 'Delete an Agent' with the exact endpoint. It also specifies the scope of destruction ('removes the saved Agent and its BotInstances'), which distinguishes it from other agent-related tools like update, activate, or clone. This is a specific verb+resource definition with no ambiguity.

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 important usage context by warning that the tool is destructive and gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS. However, it does not explicitly guide an agent on when to choose this over alternatives, such as deactivating an agent rather than deleting it. The safe-use precondition is stated, but exclusionary or alternative guidance is absent.

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 one meaningful behavioral consequence: public agents can be invited cross-app by anyone who knows the address. It does not disclose effects of switching to private or unlisted, permissions required, or what happens to existing invites. Annotations already cover mutating, idempotent, and non-destructive traits, so the additional context 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?

Two concise sentences with no redundant wording. The purpose is front-loaded in the first sentence, and the second sentence adds relevant behavioral context without unnecessary detail.

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 two-parameter setter with no output schema, the description covers the action and one meaningful consequence, but it omits the expected return value and how to obtain or specify the agent identifier. The description is adequate but leaves several operational details unstated.

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 0% schema description coverage, the description must compensate. It clarifies the visibility parameter by listing its values and explaining the public option, but it leaves agentIdOrAddress effectively unexplained beyond the parameter name. The enum values are already present in the schema, so the description adds limited semantic 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 a specific action ('Set') and resource ('Agent's visibility'), and lists the three allowed values: private, unlisted, public. It does not explicitly compare against sibling agent tools, but the purpose is unambiguous and distinct from other agent-related operations.

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 offers no guidance on when to use this tool versus alternatives, nor does it mention when not to use it. The second sentence explains a consequence of public visibility, not usage context, leaving the agent to infer the tool's applicability from its name.

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, and non-destructive behavior. The description adds useful behavioral context: `format=json` returns the bundle object directly, and the result is portable/restorable via the import tool. This goes beyond the annotations without contradicting them.

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 with no filler. The core purpose and the most important usage detail (JSON round-trip with the import sibling) are front-loaded and immediately actionable.

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 read-only export tool with strong annotations, the description is nearly complete. It explains what the tool does, how the JSON format behaves, and how to use the output. The only notable gap is the lack of detail on the zip format's behavior, but this is minor for agent 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 only 50%, and `agentIdOrAddress` has no schema description. The endpoint in the description implies it is the Agent's ID or address, but this is not explicitly explained. The `format` parameter benefits from both the schema description and the additional note about JSON round-trips, but the zip behavior is left unstated.

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 ('Export an Agent as a portable bundle') and names the exact endpoint. It also explicitly connects the output to `ethora-agents-import-v2`, which distinguishes it from sibling read tools like `ethora-agents-get-v2`.

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 clearly frames when to use export: to produce a portable bundle that can be fed back into the import tool to recreate an Agent in another App/tenant. It does not explicitly list exclusions or alternatives like clone/get, but the migration/backup 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?

Annotations already declare readOnlyHint and destructiveHint, so the description adds value by noting a side effect: 'Also sets this agent as the session's current agent context (no server-side change).' This is important behavioral context beyond the read-only claim. It also mentions auth requirements and error handling. No contradictions 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 information-dense. Every sentence adds value: the purpose, the side effect, auth prerequisites, error details, and a pointer to the sibling list tool. It is front-loaded with the main purpose and efficiently conveys all necessary guidance without 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 single-parameter get tool with read-only annotations, the description covers all aspects an agent needs: what it returns, the auth prerequisite, error semantics, and how to obtain the id. The output format isn't described, but since no output schema exists, the description's mention of the full config content suffices. No gaps are evident.

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% and includes a description for agentId that points to the list tool. The description adds context that the id is for a 'saved agent' and that it must belong to the current app (via the 404 error). This reinforces the schema meaning and adds a constraint, so it exceeds the baseline 3.

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 'Fetch' and the resource 'one reusable saved agent's full config by id', and specifies the exact contents: prompt, LLM, RAG settings, visibility. It distinguishes itself from sibling tools like `ethora-agents-list-v2` by mentioning that it fetches full config for a single agent, whereas list retrieves ids. The technical path `GET /v2/agents/:agentId` adds precision.

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 states the required auth mode ('app-token mode' after `ethora-app-select` + `ethora-auth-use-app`), and provides error conditions with 401/403 and 404 meanings. It also references how to get the agentId via `ethora-agents-list-v2`. This clearly guides when and how to use the tool, including prerequisites and where to obtain inputs.

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=false and idempotentHint=false, so the description doesn't need to restate that this is a mutating operation. It adds valuable context about the endpoint and the bundle-as-body requirement. It does not describe side effects (e.g., what happens on duplicate IDs), but the annotations cover the basic safety profile.

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 sentences, no fluff, and the core purpose is front-loaded. It efficiently conveys the endpoint, the body requirement, and the optional scoping parameter.

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 an import tool with no output schema, the description covers the essential input format and source. It doesn't mention error handling or return values, but given the annotations and the simplicity of the operation, it is sufficiently complete for an agent to call 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%, so both parameters are already documented. The description adds the critical detail that the bundle is the entire request body ('application/json body IS the bundle') and that ownerAppId defaults server-side. This goes beyond the schema's 'owning App' wording.

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 (import), the resource (Agent), and the source (bundle produced by ethora-agents-export-v2). It also specifies the exact endpoint and that the body is the bundle, making it unambiguous and distinct from create/clone siblings.

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 indicates that the input must come from ethora-agents-export-v2, which tells the agent when this tool is appropriate. It does not explicitly contrast with create-v2 or clone-v2, but the prerequisite is clear enough to route the agent correctly in most 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavior beyond that: it specifies the auth mode, the 401/403 error conditions for invalid or missing app-token mode, the return array shape (ids, names, config), and the empty-list behavior. It does not mention pagination or rate limits, but for a simple list tool the provided 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?

The description is dense but well-structured: the core purpose appears first, followed by return format, auth requirements, and error cases. Every sentence carries useful information, and the endpoint paths are integrated without excessive digression. It is slightly longer than strictly necessary because some details duplicate the schema, but it remains focused and readable.

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 one-optional-parameter read-only list tool with no output schema, the description is self-sufficient. It tells the agent what the tool does, which endpoints are involved, how appId defaults, what auth mode is required, what errors can occur, and what the response contains. An agent can invoke it correctly without needing external documentation.

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 documents the single appId parameter, including its 24-char hex format and default behavior. The description repeats these facts and adds the corresponding REST endpoint, but it does not contribute new semantic information about the parameter itself. With 100% schema coverage, 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 a precise verb and resource: 'List the reusable saved agents of an app', and expands on it with concrete endpoints. It defines what a saved agent is, which distinguishes this tool from siblings like get, create, update, delete, or clone. The agent can clearly tell this is the collection-listing operation, not a single-agent retrieval or mutation.

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 supplies clear usage context: it must run in app-token mode after ethora-app-select and ethora-auth-use-app, and it explains how the appId resolves when omitted. It also states the empty-list outcome when no agents exist. However, it does not explicitly name alternative tools like ethora-agents-get-v2 for single-agent retrieval, so the when-not guidance is only implicit.

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 indicate this is a mutating, non-idempotent operation. The description adds meaningful context beyond the annotations: the target is SOUL.MD, the content is the agent's evolving identity/private notes, and there is an operator vs. ai-service call distinction. This gives an agent useful behavioral understanding without contradicting 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?

The description is two sentences and front-loads the main action before adding context. Every sentence earns its place, and the parenthetical explaining SOUL.MD is concise and valuable.

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 two-parameter mutation tool with annotations and no output schema, the description covers the core purpose, the resource being modified, and caller context. It does not describe return values, but this is a minor gap for an append operation where the primary behavior is clearly stated.

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 0%, so the description must compensate. It partially does: 'append a fragment' strongly implies the append parameter, and 'an Agent's' implies agentIdOrAddress refers to the agent being modified. However, there is no explicit parameter-level guidance about identifier formats, content formatting, or constraints beyond what the schema's minLength 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 clearly identifies a specific action ('Append') and a specific resource (an Agent's SOUL.MD), and further clarifies that SOUL.MD is the agent's evolving identity/private notes. This distinguishes it from the sibling tool ethora-agent-soul-set, which presumably replaces rather than appends.

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 implies when the tool is appropriate: when you want to append a fragment to an agent's SOUL.MD rather than replace it. It also provides caller context by noting that it is operator-driven and that the agent can self-edit when called by ai-service. However, it does not explicitly name alternatives or state 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?

Annotations already indicate readOnlyHint=false and idempotentHint=true, which the description aligns with by stating 'Replace'. The description adds that it is 'Operator-driven', giving insight into intended use. It does not contradict the annotations. While it could disclose more about the overwrite behavior (e.g., irreversibility), the annotation coverage lowers the burden, and the description provides sufficient additional 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 two concise sentences with no filler. The core action is front-loaded, and the distinction from the append tool is included. Every word earns its place, making it highly scannable and 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?

For a simple set operation with only two parameters and no output schema, the description covers the basic action and a hint about usage context (operator-driven, alternative to append). However, it omits any mention of expected behavior beyond replacement, such as what happens to the previous SOUL.MD, any prerequisites, or error handling. Given the simplicity, it is adequate but not fully 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 only 50%: the soulMd parameter has a description, but agentIdOrAddress has none. The description does not compensate for the undocumented parameter—it provides no explanation of what 'agentIdOrAddress' refers to or its format. Since coverage is moderate and the description adds no parameter-level detail, it fails to help the agent correctly populate the undocumented field.

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: 'Replace an Agent's SOUL.MD with the provided markdown.' It identifies the resource (Agent's SOUL.MD) and distinguishes itself from the sibling tool ethora-agent-soul-append by calling itself an 'alternative to -append'. This makes it easy for an agent to understand exactly what this tool does and how it differs from similar 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 provides context that this is 'Operator-driven' and positions it as an alternative to -append, which implies it is used when the entire SOUL.MD should be overwritten rather than appended to. However, it does not explicitly state when to use this tool versus the append variant beyond this single phrase, nor does it mention any preconditions or 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?

Adds important behavioral context beyond annotations: despite being a PUT endpoint, it behaves as a partial update. It also explains practical effects of responseMode and cooldownSec. Annotations already cover idempotency and non-destructiveness, so the description supplements rather than repeats them.

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 with no filler: operation/endpoint first, then update semantics, then common use cases and a recipe pointer. 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?

The 19-parameter schema is fully documented and annotations cover idempotency/safety. The description adds operation semantics, typical workflows, and a quickstart reference. It does not describe response/error format, but the absence of an output schema makes that less critical 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% with detailed parameter descriptions, so the baseline is 3. The description adds selection value by tying prompt, responseMode, and cooldownSec to concrete scenarios and clarifies that all fields except agentId are optional.

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: 'Update a saved AI agent' with the endpoint 'PUT /v2/agents/:agentId'. It is clearly distinguishable from sibling tools like ethora-agents-create-v2, ethora-agents-delete-v2, and ethora-agents-clone-v2.

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 explains the partial-update semantics ('All fields are optional — only what you pass is updated') and gives concrete common uses: tuning the prompt after a test run, switching responseMode for turn-taking, and adjusting cooldownSec. It points to the quickstart recipe for the end-to-end flow, though it does not explicitly contrast with create/get 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?

Beyond the annotations, it discloses that the key is long-lived, revocable, shown only once, and tied to the current user's session. It also documents auth requirements and error cases (401, 404 on unsupported backends), which materially helps an agent handle the result.

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: action first, usage next, then one-time visibility and error/auth notes. Every sentence contributes a distinct operational fact with 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 two-parameter creation tool with no output schema, it covers auth, errors, usage, and the one-time display caveat, which is enough to invoke it correctly. It does not specify the exact response shape, so an agent still has to infer how the returned key is surfaced, but the 'Shown once' note mitigates this.

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 parameter descriptions are already meaningful. The text does not add further parameter-level detail, so this dimension sits at 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 the specific action 'Mint a long-lived, revocable API key' and scopes it to the currently logged-in user. This clearly differentiates creation from the sibling list/revoke tools without needing to open their schemas.

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 states the prerequisite ('logged-in user') and the practical context: the key is a Bearer token that enables API access and bypasses ethora-user-login. It does not explicitly name list/revoke as alternatives or give when-not-to-use conditions, but the creation use case 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that token values are never returned and that user auth is required, which are behavioral traits not covered by annotations. This adds value without contradicting.

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 sentences with zero redundancy. Front-loaded with the resource and fields, then the crucial security note about token values never being returned.

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 list tool with no parameters and no output schema, the description covers everything an agent needs: the resource, the returned fields, the auth requirement, and the key security caveat. Nothing essential 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?

Zero parameters, so schema coverage is trivially 100%. The description adds nothing about parameters (none exist), but the baseline for 0-param tools is 4, and the description appropriately focuses on return fields and auth.

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: 'List the current user's API keys'. Specifies exactly which fields are returned (id, name, createdAt, expiresAt). Distinct from siblings like ethora-api-key-create and ethora-api-key-revoke by the clear read-only 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?

Implies usage: for listing keys of the current user, and notes auth requirement. Does not explicitly contrast with create/revoke, but the action is unambiguous and the scope ('current user') 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?

Annotations already indicate destructive and idempotent behavior. The description adds valuable context beyond annotations: clients using the key stop working immediately, authentication is required, and unknown ids return 404. This directly informs the agent of consequences and preconditions.

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 is purposeful and information-dense: purpose, immediate consequence, auth requirement, and error case. The core action is front-loaded, and there is 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 single-parameter destructive action with annotations covering safety and idempotence, the description covers purpose, auth, error handling, and real-world effect. Nothing essential is missing 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 schema already documents the id source at 100% coverage. The description adds ownership meaning ('current user's API keys') and error behavior for unknown ids, going slightly beyond the schema while remaining relevant to using the parameter correctly.

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 ('Revoke'), the resource ('API keys'), ownership scope ('current user's'), and the selection mechanism ('by id'). It is clearly distinct from the sibling create/list tools without needing to inspect them.

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 intended use is clear: revoke a specific API key belonging to the current user. It also provides useful contextual warnings (immediate effect) and error semantics, though it does not explicitly contrast with alternatives like app-token revocation.

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?

Even though annotations mark readOnlyHint=false, the description adds meaningful side-effect context: a fresh appId is allocated, the caller becomes owner, and the action counts against the owner's plan limit. It also documents expected errors (401/402/403/422) and the return value, going well 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?

Three tightly packed sentences: the first covers behavior and side effects, the second covers auth and errors, the third points to the related alternative. Every sentence adds information and the most important fact 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 single-parameter creation tool with no output schema, the description covers purpose, auth prerequisite, side effects, error conditions, and the return value. It is fully sufficient for an agent to decide when and how to invoke 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?

The input schema already has 100% description coverage for displayName with a clear human-readable explanation. The tool description adds no additional parameter-level detail, so 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 opens with a specific verb and resource: 'Create a new Ethora app (tenant) owned by the currently logged-in user.' It further clarifies the outcome by stating it allocates a fresh 24-char hex appId and sets the caller as owner, which clearly distinguishes this from related tools like ethora-b2b-app-create.

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 states the intended context: user-auth mode with an active session via ethora-user-login first. It also names the alternative for server-side provisioning, ethora-b2b-app-create, making the boundary between the two 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?

The description discloses important side effects beyond the annotations: every created room is listed in defaultRooms, pinned=true only affects new users (existing users are not added), and the response includes the new room object with its JID. It also lists concrete auth and error conditions, which is substantial 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 dense but well-organized: core action first, then side effects, return value, auth, and errors. Every sentence earns its place and there is 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 create tool with no output schema, the description covers prerequisites, side effects, return shape, and error codes. An agent has enough information to invoke it safely and understand the result.

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, but the description adds meaningful parameter nuance: pinned=true does not add existing users, and rooms are placed in the app's defaultRooms. This goes slightly beyond the schema 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 begins with a specific verb and resource: 'Create a new chat room (MUC room) inside an app the caller owns.' This clearly distinguishes the tool from siblings like ethora-app-delete-chat and chat-message 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?

It gives clear context for when the tool is appropriate: the caller must own the app and have an active user-auth session. It explains pinned vs. non-pinned behavior for auto-join, though it does not explicitly name alternatives or when-not-to-use conditions.

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 annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them by detailing what gets removed (chat rooms, files, indexed RAG sources, bot config), immediate user sign-out, irreversibility, the environment variable gate, and error conditions. This is rich behavioral context with no contradiction.

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?

Dense but well organized: primary effect and consequences first, then safety gate, auth requirements, error semantics, and a related alternative. Every sentence adds operational value without 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?

For a destructive single-parameter tool, the description covers what the action does, what it destroys, who may call it, what can go wrong, and what safer alternative exists. Nothing essential is missing 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 coverage is 100% and the appId parameter is already well documented with its format and how to obtain it. The description adds ownership and 404 context but does not substantially extend parameter 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?

States a specific verb and resource ('permanently delete an Ethora app the caller owns') and lists concrete consequences. It clearly distinguishes itself from related operations like ethora-app-delete-chat and ethora-app-update.

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 the caller must own the app, requires user-auth active session, and names the safety gate ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true. It also points to an alternative for deactivating the bot via ethora-app-update with botStatus: 'off'.

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?

Beyond the destructiveHint/readOnlyHint annotations, the description discloses what is destroyed (MUC room, archive, affiliations), irreversibility, the configuration gate, authentication mode, and exact 401/403/404 failure semantics. This is rich behavioral context that annotations alone do not provide.

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 dense but every sentence carries operational value: effect, permanence, gate, auth, and errors. The most important fact (permanent deletion) is front-loaded, and there is 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 destructive two-parameter tool with no output schema, the description covers the outcome, prerequisites, configuration requirement, and all likely failure modes. Nothing essential for an agent to call it safely 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 schema already documents appId's default behavior and chatJid's format and source tools. The description adds no parameter-specific detail beyond the schema, so the baseline 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 states a specific verb and resource: 'Permanently delete a chat room from an app the caller owns' and details the exact scope (removes MUC room, message archive, member affiliations). This clearly separates it from sibling tools like ethora-app-delete (app-level deletion) and ethora-app-create-chat (creation).

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 clear invocation context: user-auth mode with an active session, app ownership, and the ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true gate. It does not explicitly name alternatives or state when not to use it, but the prerequisites and error conditions effectively guide selection.

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, openWorld, idempotent, and non-destructive hints, lowering the bar. The description adds useful behavior: format=json returns the bundle object directly, include selects sections, and the result feeds import. It leaves format=zip behavior unspecified, but this is a minor gap given the strong annotation coverage.

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 focused sentences with the core purpose front-loaded, followed by format behavior and import workflow guidance. No filler, no restatement of schema fields.

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 read-only export tool with rich annotations, the description covers the essentials: endpoint, format effect, include usage, and the downstream import step. The only missing items are the default include sections and what zip format returns, which would be useful given the absent 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?

Schema documents appId and include but leaves format with only an enum. The description adds real semantics by explaining that format=json returns the bundle object directly and by giving a concrete include example, compensating for the undocumented format behavior. appId's B2B-mode nuance remains in the schema, which is acceptable.

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 ('Export'), a specific resource ('App'), and a concrete deliverable ('portable bundle'), along with the exact endpoint. The explicit reference to ethora-app-import-v2 distinguishes this from the import counterpart and other app-related 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?

Provides clear workflow context by directing the agent to feed the result to ethora-app-import-v2, establishing when this tool is needed. The schema adds appId context for B2B mode. However, it does not explicitly state when not to use it or contrast it with agent-level export 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful context beyond annotations: auth mode ('user-auth mode, active session'), the dependency on `ethora-app-select`, and specific error codes (400 no app selected, 401 not logged in). This is useful operational detail not present in the annotations. No contradictions found.

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: a first sentence states the core action and outcome, a second sentence covers auth and errors, and the final line names the related tool. Every sentence earns its place, and the key purpose is front-loaded. 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 simple read-only tool with no parameters and no output schema, the description covers all essentials: what it returns (rooms with JIDs and titles), the auth requirement, the dependency on a previously selected app, error conditions, and the alternative for explicit appId. An agent has everything needed 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 is empty (0 parameters), so there is nothing to document. The description correctly does not invent parameters. Baseline for 0 params is 4, and the description does not need to add anything about parameters. It effectively communicates that no parameters are needed.

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 ('List') and a specific resource ('default chat rooms (MUC rooms) of the currently selected Ethora app'), and clarifies the auto-join behavior. It also distinguishes itself from the sibling by naming the alternative that takes an explicit appId. This is a clear, unambiguous 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 explicitly references the sibling tool `ethora-app-get-default-rooms-with-app-id` and explains when to use it (to pass `appId` explicitly). It also states the prerequisite that an app must be selected via `ethora-app-select`. This gives clear when-to-use and when-not-to-use guidance, with an alternative 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses authentication requirements ('user-auth mode, active session'), permission prerequisites ('read access: ownership or room membership'), and enumerates the relevant error cases (400, 401, 403, 404). This is substantial behavioral context that the annotations do not provide, and it does not contradict 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?

The description is compact and front-loaded: the core action and return values appear first, followed by tightly packed auth and error information. Every clause earns its place with no repetition 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 tool with one optional parameter and no output schema, the description is nearly complete: it covers return payload fields, default parameter behavior, auth requirements, and failure modes. The only material gap is the lack of explicit guidance distinguishing this tool from the similarly named ethora-app-get-default-rooms sibling, leaving the agent to infer the difference from the name.

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 fully describes appId, including that it is optional and defaults to the app most recently passed to ethora-app-select. The description only paraphrases this behavior and adds no new parameter format or usage semantics beyond the schema, so the 100% schema coverage 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 verb and resource: 'List the default chat rooms of a specific Ethora app,' and it specifies the returned fields (JIDs and titles). However, it never references the near-identical sibling ethora-app-get-default-rooms, so differentiation must be inferred from the tool name rather than the description.

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 invocation context: appId is optional and defaults to the currently selected app, and it states the required auth mode and read-access conditions. It does not explicitly explain when to choose this tool over ethora-app-get-default-rooms or other listing siblings, so alternatives are not 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 flag readOnly=false, idempotent=false, and destructive=false. The description adds useful behavioral context by specifying B2B/tenant-actor auth, that the JSON body is the bundle, and that domainNameOverride renames the imported domain. It does not detail side effects such as duplicate-import behavior, but the annotation set lowers the burden.

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 deliver the action, source, endpoint, body format, auth mode, and the override behavior. No filler or repetition of the annotations.

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 auth, endpoint, bundle provenance, and the optional override, which is enough to make the call. It does not clarify the apparent optionality of bundle (required parameters are 0) or describe the success/error return shape, but those are secondary for 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%, so the baseline is 3. The description enriches the bundle parameter by naming its producer (ethora-app-export-v2) and explaining the body transport semantics, going beyond the schema's 'exported bundle object' wording. domainNameOverride's effect is essentially restated, not expanded.

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: 'Import an App from a bundle produced by ethora-app-export-v2.' It also states the exact endpoint (POST /v2/apps/import), which separates it from create/update/export siblings.

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 usage context: use this when you have a bundle produced by ethora-app-export-v2. It does not explicitly contrast with ethora-app-create or state when not to use it, so it stops short of full 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?

Annotations already mark it read-only and non-destructive, and the description adds valuable behavioral detail: the exact return fields, the 401 error when not logged in, and the empty-list result when the user owns no apps. This fully informs an agent of expected behavior.

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-ordered: the core purpose comes first, followed by return shape, auth requirements, error behavior, and related tools. Every sentence contributes useful information 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?

With no output schema, the description properly explains what the tool returns (array with appId, displayName, domainName, ownership and bot-status metadata). Combined with annotations and the empty-parameter schema, nothing necessary for correct invocation 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?

The tool has zero parameters and 100% schema coverage, so there is no parameter ambiguity. The baseline for a zero-parameter tool is 4; the description needs no further parameter explanation.

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 ('List') with a clear resource ('all Ethora apps (tenants) owned by the currently logged-in user'). It distinguishes this tool from the many app-related siblings by emphasizing ownership scope and the current user.

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 clear prerequisites (user-auth mode, active session after ethora-user-login) and downstream use cases via the Related line. It does not explicitly contrast with alternatives, but no equivalent list sibling exists, so this is strong 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?

The annotations include idempotentHint=true and destructiveHint=false, indicating a non-destructive, idempotent operation. The description adds valuable behavioral context: it stores `currentAppId` and possibly `appToken`, defaults the auth mode to app-token under conditions, and notes that errors are deferred to the first app-scoped API call. This goes beyond annotations by explaining the session state mutation and error handling.

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 yet informative, with key information front-loaded. It avoids redundancy and presents the most critical behavioral effects (storing context, auth mode defaults) early, followed by error handling and related tools. Every sentence adds value.

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 (3 parameters, no output schema, no nested objects), the description is adequately complete. It covers all necessary aspects: purpose, parameters, auth, errors, and relation to siblings. The only minor omission is explicit mention of how to retrieve a valid `appId` (though the parameter description covers that), so it is nearly 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 clearly. The description reinforces the semantics of `appToken` and `authMode` by explaining their interplay (e.g., appToken defaults auth mode to app-token unless overridden), but does not add new meaning beyond that. Since coverage is high, 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 clearly states the tool's purpose: to set the current app context for the session, enabling app-scoped tools to omit their `appId` argument. It uses specific verbs ('set') and resource ('current app context'), and mentions the effects on `appId` and `appToken`. While the name and title are somewhat generic, the description adds precise detail about the session context and its implications.

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 states when to use this tool: to set the current app context, and pairs it with `ethora-auth-use-app` as related. It also clarifies that no authentication is required to set the context, and that a non-existent `appId` is not validated here. This provides clear guidance on prerequisites and when to use it versus 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?

The description goes well beyond annotations by disclosing that the secret is returned exactly once and can never be retrieved again, instructing the agent to capture it immediately, and listing auth and error behavior. Annotations only signal readOnly=false, idempotent=false, destructive=false; the description adds critical 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 dense but well-organized: purpose, one-time-secret warning, return fields, auth, errors, and related tools. Every sentence earns its place, and the most critical warning 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?

With only 3 optional parameters, no output schema, and no nested objects, the description covers what the agent needs: return shape, irrecoverable secret, auth prerequisites, error codes, and related tools. Nothing essential is missing 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?

Schema description coverage is 100%, and the schema already documents appId's default behavior, label's purpose, and timeoutMs default. The description does not materially add parameter meaning beyond the schema, so the baseline 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 opens with 'Mint a new app token for an app,' a specific verb and resource, and clarifies it returns the token plus tokenId. It also names related management tools, making the create-vs-manage distinction explicit and separating it from list/rotate/revoke siblings.

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?

Auth prerequisites (B2B mode + b2bToken) and common error cases are stated directly. Related tools are named, though it does not explicitly phrase 'use this when you need a new token' as an exclusionary guideline; still, the intended 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral detail that secret token values are never returned (only shown once at create/rotate time), which is crucial for agents to avoid expecting secrets in responses. It also discloses auth requirements and error codes, adding value 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?

The description is two sentences: the first states the core function and return details, the second covers auth and error codes. It is front-loaded with the primary purpose and wastes no words. 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?

For a simple list operation with 2 optional parameters, the description covers the essential context: what it returns, the auth prerequisite, and error conditions. The absence of an output schema is mitigated by the description listing the returned metadata fields. It could mention pagination or result limits, but these are not critical for this tool given its simplicity.

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 the parameters with descriptions for both appId and timeoutMs. The description itself does not add parameter-specific semantics, but since the schema is complete, the baseline of 3 is appropriate. No additional information is needed from the 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 tool lists app tokens and specifies the metadata fields returned (tokenId, label, timestamps, status), explicitly distinguishing it from token creation, rotation, and revocation siblings. The purpose is unambiguous and actionable for an agent.

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 includes an explicit auth requirement (B2B mode with ethora-auth-use-b2b and a configured b2bToken), which tells an agent when the tool is usable. It also lists error conditions (401/403, 400, 404) that clarify failure scenarios. However, it doesn't explicitly contrast with create/rotate/revoke alternatives, though the operation name and description make that obvious.

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 indicate destructive and idempotent behavior, but the description adds crucial details: immediate invalidation, no replacement issued, and specific auth prerequisites. It also discloses expected error conditions, which is beyond what annotations cover.

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, front-loaded with the core action and effect, then efficiently covers auth, errors, and related tools in a second sentence. Every sentence adds value without 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 destructive operation, it fully covers prerequisites (B2B), how to obtain the required tokenId, what to expect on success/failure, and alternatives. Nothing an agent needs to call it correctly 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 coverage is 100% and each parameter already has a clear description. The description reinforces the source of tokenId and the default behavior of appId, but adds little new parameter-specific meaning beyond the schema. It earns a 4 for the useful cross-reference to list-v2.

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 ('permanently revoke'), the resource ('app token'), and the identifier ('by tokenId'), and immediately conveys the consequence (stops working, auth failures). It distinguishes itself from sibling tools like rotate (revoke-and-replace) and list (source of tokenId).

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 context: B2B mode requirement, error codes for common failure scenarios, and points to related tools (list for tokenId, rotate for revoke-and-replace). This gives the agent clear guidance on when to use this tool and what alternatives exist.

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 that the old token is revoked immediately and the new secret is returned exactly once, implying that repeating the call with the same `tokenId` would not yield the same secret again. This contradicts the annotation `idempotentHint: true`, which claims the operation is idempotent. Because the description contradicts a stated annotation, it earns a score of 1 and flags an annotation contradiction.

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 well-structured and front-loaded with the core purpose. It packs essential operational details (immediate revocation, one-time secret, auth requirements, error codes) into a concise block without unnecessary fluff. It earns a 4 rather than a 5 because it could be slightly more streamlined (e.g., the error list is a bit verbose), but it is still efficient and clear.

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 operational consequences (immediate revocation, one-time secret), auth constraints, and likely error codes. Since there is no output schema, it explains the critical output ('new secret value is returned exactly once') adequately. However, it leaves some ambiguity about idempotency (a conflict with annotations) and does not describe the response format beyond the secret, so it is not fully complete. Given the tool's destructive nature and the absence of an output schema, a 4 is reasonable.

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 for all four parameters, so the schema already explains their meanings. The description adds a little extra context (e.g., that `tokenId` is the token to revoke, and that `appId` defaults to the selected app), but this is largely redundant with the schema. Baseline 3 is appropriate because the description does not significantly deepen parameter understanding 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 specific action: 'Rotate an app token: revoke an existing token and issue a replacement in one step.' It names the resource and the verb, and it distinguishes itself from the sibling `ethora-app-tokens-revoke-v2` which revokes without a replacement. This makes the tool's purpose immediately obvious.

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 explicit usage context: it mentions the required B2B auth mode and the prerequisite of having a `b2bToken`. It also explicitly names a related alternative (`ethora-app-tokens-revoke-v2`) and the condition for choosing it ('to revoke without a replacement'). This is clear, actionable guidance on when to use this tool versus 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?

The description adds substantial value beyond the annotations: it discloses partial-update behavior (omitted fields unchanged), requires user-auth and ownership, and enumerates specific error conditions with status codes. This gives the agent a precise mental model of side effects and 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 compact and front-loaded: purpose and field list first, then partial-update behavior, then auth and errors. Every sentence carries operational information, with no filler 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 six-parameter mutation tool with no output schema, the description covers the essential operational context: what fields change, partial-update semantics, auth requirements, ownership constraint, and all relevant error paths. An agent has enough information to call the tool 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%, so the schema already documents each parameter thoroughly. The description still adds useful context by framing all listed fields as mutable app attributes and stating that omitted fields remain unchanged, which clarifies how the optional parameters behave collectively.

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 ('Update'), a clear resource ('an app the caller owns'), and enumerates the exact mutable fields. It also clarifies the partial-update semantics, making the tool's purpose unambiguous and easily distinguishable from app create/delete/select siblings.

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 makes the usage context clear: the caller must own the app and have an active user-auth session, and only mutable fields are affected. It does not explicitly name alternative tools or state when not to use it, but the ownership and field-scope guidance is enough for an agent to select it appropriately.

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 the annotations by explaining that the tool mutates the session's active auth mode, requires a pre-configured appToken, and errors if one is missing. Annotations already cover idempotency and non-destructiveness, so the description appropriately supplements them rather than repeating them.

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 well-structured and front-loaded with the primary action, then uses labeled 'Auth', 'Errors', and 'Related' sections to convey prerequisites, failure modes, and sequencing. Every sentence earns its place, and there is no redundant or irrelevant 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 parameterless session-state switch with no output schema, the description is complete: it states the effect, prerequisites, error condition, and recommended usage order. An agent has enough information to invoke it correctly and to understand the consequences.

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?

This tool has zero parameters, and the schema description coverage is 100%, so there are no parameter details to clarify. The description still adds useful context about the configured appToken that indirectly affects behavior, which is appropriate for a parameterless tool.

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 verb and resource: it switches the session's active auth mode to app-token, which is specific and actionable. It does not explicitly name sibling auth tools like ethora-auth-use-b2b or ethora-auth-use-user, but the app-token scope makes the distinction reasonably clear.

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 concrete prerequisites and sequencing: appToken must already be configured via ethora-configure, ETHORA_APP_TOKEN, or ethora-app-select, and it recommends using this tool after ethora-app-select. It does not explicitly list when not to use it or mention alternative auth-mode tools, but the usage 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?

The description adds substantial behavioral detail beyond the annotations: it discloses the session-scoped side effect, the exact x-custom-token header mechanism, the required JWT type, how to configure it, and the error case when it is missing. These are precisely the operational details an agent needs to invoke this tool safely.

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 compact, front-loaded sentences cover purpose, auth requirements, errors, and related tools. Every sentence contributes operational value and nothing is redundant with the schema or annotations.

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 zero-parameter state-switching tool, the description thoroughly covers purpose, prerequisite, error behavior, and related tools. It omits an explicit comparison with app/user auth siblings and a success return value, but neither is essential given the provided 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?

The tool has zero parameters, so there is no schema semantics to clarify. Given the zero-parameter baseline, the description does not need to compensate for any parameter documentation gaps.

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 the specific action—switching the session's active auth mode to B2B—and states the concrete consequence: subsequent calls authenticate as a tenant actor via the x-custom-token header. The B2B scope and tenant-actor wording distinguish it clearly from the sibling auth-use-app and auth-use-user 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 makes the usage context clear: server-side automation, paired with specific B2B tools. It also states the prerequisite (b2bToken configured via ethora-configure or ETHORA_B2B_TOKEN env) and the failure mode if it is absent. It does not explicitly call out auth-use-app or auth-use-user as alternatives, but the context is sufficient for correct selection.

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 behavioral details beyond the annotations: it states the switch itself requires nothing and causes no errors, but downstream tools will return 401 until login succeeds. This gives agents accurate expectations about side effects and dependencies. It does not contradict any annotation and adds useful context about the required token.

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 concise sentences that are front-loaded with the core purpose, then add required context (auth requirements, errors, related tool) in a logical order. No extraneous words; every sentence contributes value.

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 has no parameters and no output schema, the description covers the essential information: what it does, prerequisites, error behavior, and a related next step. It omits explicit mention of alternative auth modes, but those are visible in sibling names, so the description is complete enough for effective use.

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?

There are no parameters, so the schema trivially covers 100% of them. The baseline for a zero-parameter tool is 4. The description adds no parameter information because none exists, which 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 a specific action: 'Switch this session's active auth mode to user-session' and the outcome: 'subsequent calls authenticate as a logged-in Ethora user.' This is not a tautology and distinguishes the user-session mode from other auth modes present in the sibling tools (ethora-auth-use-app, ethora-auth-use-b2b), though it does not explicitly name them. It is slightly under the top score because it could have explicitly contrasted with those siblings.

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 explicit usage context: it states the prerequisite (login via ethora-user-login storing a user token), the error behavior (downstream 401 until login), and a related next step ('follow with ethora-user-login'). It does not explicitly say when to use this tool vs the app or b2b auth switches, but the provided flow is clear for the user-auth path.

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 goes well beyond the annotations (which only indicate non-read-only, non-destructive, non-idempotent) by disclosing critical behaviors: best-effort source ingest and bot activation (app is still created if later steps fail), asynchronous crawl/embedding that continues after return, a per-step log including appId, internal auth mode switching, error handling with partial step log on app creation failure, and best-effort restoration of the previous auth mode. These details are essential for an agent to correctly interpret outcomes and handle failures, and they are not contradicted by 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?

The description is structured logically: first the core purpose, then the best-effort and async caveats, then auth and error behavior, and finally the related variant. Every sentence delivers necessary information without redundancy or filler. The front-loaded purpose sentence immediately tells an agent what the tool does, and the subsequent details are packed but concise. It is appropriately sized for the complexity of the tool.

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 (14 parameters, multi-step orchestration, auth switching, async behavior), the description covers all essential aspects: the overall flow, failure semantics, async continuation, auth requirements, return value (per-step log with appId), and related tool. There is no output schema, but the description mentions the key return element. Nothing an agent needs to call this tool correctly is missing, and the description is sufficiently detailed for a high-complexity 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?

The input schema provides descriptions for all 14 parameters (100% coverage), so the description does not need to repeat their definitions. The description does add some contextual meaning, such as noting that source ingest is best-effort and that crawl/embedding continues asynchronously, which affects how the `docs`, `crawlUrl`, and `followLink` parameters should be interpreted. However, this is supplementary; the schema already covers the parameter semantics adequately, 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 precise, actionable statement: 'One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot.' It names the exact sequence of operations and the resources involved, and it distinguishes itself from a sibling by naming `ethora-b2b-app-provision` as the rooms+tokens variant. This leaves no ambiguity about what the tool does or how it differs from similar 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 mentions the related variant `ethora-b2b-app-provision` and frames this tool as the one-call orchestrator, implying it is the right choice when you want to perform all steps in a single invocation. It also states the auth prerequisite (B2B mode) and notes that source ingest and bot activation are best-effort, which influences whether this is appropriate for a given use case. However, it does not enumerate all possible alternatives (e.g., individual tools like ethora-app-create + ethora-sources-docs-upload), though that omission is acceptable given the tool's self-description as an orchestrator.

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 goes well beyond the annotations by disclosing the side-effect scope: it allocates a fresh 24-char hex `appId`, does not create tokens/rooms/bot, and returns the app object. It also documents auth requirements (B2B mode + `b2bToken`) and specific error codes (401/403, 422), giving the agent a clear behavioral contract.

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 core purpose, then efficiently covers scope exclusions, return value, auth, errors, and related tools in just a few sentences. No information is redundant or unnecessary.

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 this is a simple one-parameter create operation with no output schema, the description covers all necessary context: what the tool does, what it does not do, what it returns, auth prerequisites, error conditions, and related alternatives. Nothing critical is missing 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?

With only one parameter and 100% schema description coverage, the schema already fully documents `displayName`. The description adds only marginal value by mentioning '422 invalid displayName' but does not provide additional semantic detail about the parameter 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 clearly states a specific action ('Create a new Ethora app (tenant) server-side using B2B auth') and differentiates it from the similarly named `ethora-app-create` by identifying it as the partner/integrator equivalent. It also narrows the scope by explicitly listing what it does NOT do ('does not create tokens, rooms, or a bot'), making the purpose 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 provides clear guidance on when to use this tool: when operating in B2B mode, and it names the direct alternative `ethora-app-create` for the non-B2B path. It also points to `ethora-b2b-app-bootstrap-ai` / `ethora-b2b-app-provision` for an all-in-one flow, so an agent can decide between this minimal creation step and a more comprehensive operation.

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?

Beyond the annotations (readOnlyHint false, openWorldHint true), the description discloses critical behaviors: later-step failures don't undo earlier steps, tokens are returned only once and must be captured, errors abort with a partial step log, and the previous auth mode is restored best-effort. This is rich, non-obvious 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?

Every sentence earns its place: purpose/steps, failure semantics, return behavior, auth requirement, error behavior, and sibling differentiation. It is dense but not bloated, and the most decision-relevant 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 complex multi-step tool with no output schema, the description covers the full call sequence, return shape, failure semantics, auth prerequisite, and relationship to alternatives. Nothing an agent needs to invoke this correctly 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?

The input schema has 100% description coverage across all 10 parameters, so the description does not need to restate parameter meanings. It adds no parameter-level detail beyond the schema, but the schema already carries that burden, so 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 uses a specific verb and resource ('One-call B2B orchestrator') and enumerates exactly what happens: create app, mint tokens, provision rooms, configure/enable bot. It also distinguishes itself from the closely related sibling ethora-b2b-app-bootstrap-ai, making the tool's scope 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?

It states the auth prerequisite explicitly ('B2B mode ... + configured b2bToken'), describes the orchestration use case, and names the alternative tool with a clear differentiator: bootstrap-ai does sources+bot but not tokens/rooms. This is strong routing 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?

Annotations indicate a mutating operation (readOnlyHint=false) and the description adds meaningful behavioral context: the legacy status, the auto-provision change, and the 422 BOT_NOT_INITIALIZED failure mode. It doesn't contradict annotations, and it goes beyond the structured data by explaining when the operation will fail.

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, then explains the error, the alternatives, and the valid use case. It's slightly dense but every sentence carries information; 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 mutation tool with no output schema, the description covers the key operational details: when to use, when not to use, the failure mode, and the forward path. It doesn't discuss the effect of omitting botTrigger, but the schema covers that.

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 (appId and botTrigger), each with clear descriptions. The tool description does not add extra parameter semantics beyond the schema, so 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 states a specific action (enable a legacy per-app aiBot) with clear scope (B2B auth) and distinguishes it from the forward path (Agents API). It explicitly names alternative tools, making differentiation 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 explicit when-to-use guidance: valid only for apps with a pre-existing legacy aiBot, and names the forward-path alternatives (ethora-b2b-app-bootstrap-ai or ethora-agents-create-v2 + ethora-agent-invite-to-chat). It also warns about the 422 error on clean apps, leaving no 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 indicate idempotentHint=true and destructiveHint=false. The description adds beyond that by noting that 'the configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling restores the same behavior,' which clarifies the non-destructive nature. It also discloses error codes. No contradiction with annotations; it reinforces them.

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 delivering a distinct piece of information: the core action, the preservation side effect, and auth/errors/related tool. It is front-loaded with the primary purpose and has no filler. 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?

For a tool with one parameter, annotations covering idempotency and non-destructiveness, and no output schema, the description covers the essential aspects: purpose, side effects, auth requirements, errors, and related tool. It does not describe the return value or success message, but that is minor given the simple nature and absence 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 schema already describes the appId parameter with 100% coverage ('24-char hex appId. Required in B2B mode unless already set via ethora-app-select; ignored in app-token mode.'). The description adds value by tying the parameter to the auth modes and explicitly stating when it is needed, reinforcing the conditional requirement.

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: 'Turn the AI bot off for an app (sets bot status: "off") — it stops responding.' It names the specific resource (app) and the effect. It distinguishes itself from the sibling ethora-bot-enable-v2 by explicitly referencing it as the reverse operation, so an agent can immediately tell them apart.

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 usage context by specifying auth modes ('app-token mode OR B2B mode with an explicit appId') and error conditions (401/403, 404). It also names the complementary tool ('Related: ethora-bot-enable-v2 to turn back on'). However, it does not explicitly state when NOT to use it (e.g., when deletion is preferred), leaving some implicit 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?

Beyond the annotations, the description discloses a key behavioral trait: it fails with 422 BOT_NOT_INITIALIZED on clean API/B2B-created apps. It also clarifies the legacy-only applicability, which helps an agent anticipate failure modes. The idempotentHint and destructiveHint annotations are not contradicted; the description adds useful error 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 compact and front-loaded with the core purpose, followed by a necessary error/alternative note and a validity statement. Each sentence contributes information an agent needs to decide whether to call this tool. It is slightly dense but not bloated.

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, the description covers the critical decision factors: what it operates on, which auth modes are valid, when it will fail, and what alternatives to use. It does not describe the success response or side effects beyond 'enable', but the annotations cover idempotency and non-destructiveness. Overall it is sufficiently complete 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?

Schema description coverage is 100%, so both appId and trigger are already documented in the schema. The description mentions auth modes (app-token or B2B) that contextualize appId, but it does not add meaning beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 and resource: 'Enable the LEGACY per-app aiBot using app-token or B2B auth.' It also distinguishes itself from the broader bot/B2B toolset by emphasizing 'legacy' and 'per-app' scope. This clearly separates it from siblings like ethora-b2b-bot-enable and ethora-agents-create-v2.

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 tells when not to use the tool: clean API/B2B-created apps have no legacy aiBot, so they would get a 422 BOT_NOT_INITIALIZED. It names concrete alternatives (ethora-agents-create-v2 + ethora-agent-invite-to-chat, or ethora-b2b-app-bootstrap-ai) and states the valid use case: apps that already have a legacy aiBot. This is 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds useful behavioral context beyond annotations by explicitly stating auth requirements (app-token mode or B2B with appId) and likely errors (401/403, 404). It does not describe output shape, but for a single-resource config read, the listed fields provide sufficient expectations.

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 first sentence states what the tool reads, then auth/error/related information follow in short, scannable sentences. Every sentence earns its place without 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?

For a simple read tool with one optional parameteramenities, the description covers function, auth modes, error conditions, and related mutation tool. No output schema exists, but the description enumerates expected response contents. An agent has everything necessary to invoke the tool correctly and interpret the result.

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 appId thoroughly, including format, mode-specific requirements, and the 'ignored in app-token mode' behavior. The description's Auth line largely repeats the schema's parameter semantics rather than adding new meaning. Since schema coverage is 100%, the baseline is 3, and no additional parameter detail is needed.

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 ('Read') and identifies the exact resource ('current AI bot configuration for an app'), then enumerates the key config fields: status, trigger, prompt, greeting, LLM provider/model, RAG settings, and widget config. It also distinguishes from the update sibling by naming ethora-bot-update-v2 as the related mutation tool, so an agent can immediately understand this is the read counterpart.

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 contextual guidance on auth modes: app-token mode requires no appId, while B2B mode requires an explicit appId. It also points to ethora-bot-update-v2 when a configuration change is needed)Skip(). However, it does not explicitly contrast itself with other potentially similar read tools like ethora-agents-get-v2, so some ambiguity remains about when exactly to prefer this over related-but-different 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral value by specifying the data is 'live' and includes 'recent activity', which is not implicit from the annotations. It gives enough context for a diagnostic read operation, though it doesn't discuss edge cases or error conditions.

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 two sentences with no filler. The endpoint and core behavior are front-loaded, and the purpose ('for troubleshooting') is tucked at the end. Every word 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?

For a read-only, two-parameter diagnostic tool with no output schema, the description states what the call returns (live status and recent activity) and the endpoint. It covers the essentials. It could expand on what 'activity' includes, but given the simplicity and the annotations, this is sufficient for an agent to call and interpret the result at a high level.

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 0%, so the description must compensate. It includes the URI pattern with placeholder names (:idOrAddress, :botInstanceId) and the parameter names themselves are self-explanatory. However, the description does not explicitly define what counts as an agent ID/address or bot instance ID, leaving some interpretation to the agent. It adds some value but does not fully explain parameters.

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 ('Diagnose') and resource ('BotInstance') and includes the endpoint, making the tool's purpose clear. It distinguishes itself from siblings like ethora-bot-instance-status by mentioning 'recent activity' and 'troubleshooting', so an agent can tell it apart even without opening other schemas.

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 for when to use this tool ('for troubleshooting') and what it returns ('live XMPP/ai-service status and recent activity'). However, it does not explicitly name alternatives (e.g., ethora-bot-instance-status) or state when not to use it, so it falls short of full 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds little beyond the endpoint and inverse relation, such as side effects on message delivery or chat membership, but it does not contradict 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?

A single sentence packs in the action, resource, endpoint, and inverse relationship with no wasted words. 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?

For a simple destructive operation, the description is adequate, especially with annotations carrying the safety profile. But it leaves parameter semantics thin, gives no postcondition information, and relies on the reader to infer usage from the inverse relationship.

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 only 33%, and the description adds no meaning for `agentIdOrAddress` or `botInstanceId`. The endpoint template gives partial clues, but the description does not compensate for the two undocumented parameters, and `chatJid` was already explained in 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: 'Remove a BotInstance from a chat room,' and includes the exact endpoint. It also names `ethora-agent-invite-to-chat` as the inverse, making the tool's purpose immediately clear and distinguishable from related sibling 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 inverse relationship with `ethora-agent-invite-to-chat` gives clear context for when this tool applies: it undoes an invitation. However, it does not explicitly state when not to use it or compare it to other bot-manipulation siblings such as bot-disable or instance-status.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the operation is safe and non-mutating. The description adds the default behavior of appId (caller's App by default) which is valuable beyond annotations. It does not describe pagination or response format, but with annotations covering safety, the bar is lower and the provided detail 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 a single sentence that is concise, direct, and front-loads the purpose ('List BotInstances') followed by the optional filtering. No filler words, making it 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?

The tool is simple with two optional filters and no output schema, which lowers complexity. The description covers the purpose and the default for appId, which is essential. However, it lacks information about pagination, sorting, or any limits, which might be relevant for a listing tool. Given the simplicity and annotations, this seems adequate but not overly detailed.

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 defines two parameters (appId and agentId) with no descriptions, but their names are self-explanatory. The description mentions filtering by these fields, adding some semantic meaning beyond their names, but does not provide type, format, or behavior details. Since schema coverage is 0%, the description partially compensates but is not thorough – summing up to a baseline 3.

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 identifies the resource ('BotInstances') and the action ('List'), with a brief scope. It mentions filters (appId and agentId), which helps distinguish it from sibling tools like 'ethora-agents-list-v2' that may list different resources (agents vs bot instances).

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 implies the tool is for listing bot instances with optional filters, and the context that appId defaults to caller's App is provided. However, it does not explicitly state when to use this tool versus alternatives like 'ethora-agents-list-v2' or 'ethora-bot-get-v2', but the naming and context make it relatively 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?

Annotation Contradiction: annotations declare readOnlyHint=true, but the description describes a state-changing operation: 'Off detaches it from XMPP; on re-spawns the XMPP client live.' This directly conflicts with a read-only semantic. Because the description contradicts the annotation, the score is 1.

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 short sentences, no filler, and the primary action is front-loaded. The effect of each status is immediately useful and compactly stated.

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 tool with an enum, the description is nearly complete: it names the resource, the parameter role, and the behavioral effect. The main gaps are the lack of explicit return-value expectations and the fact that the misleading readOnlyHint annotation undermines trust in the surrounding metadata, but the description itself gives enough to invoke the 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?

The schema has 0% description coverage, so the description carries the semantic burden. It maps botInstanceId to the target BotInstance and status to 'on' or 'off,' while also explaining the runtime consequence of each status. It does not detail the ID format, but the enum and mapping are sufficient for correct invocation.

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: 'Turn a specific BotInstance on or off.' It clarifies the action beyond the title by explaining that 'off detaches it from XMPP; on re-spawns the XMPP client live,' which distinguishes this from generic status or list operations.

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 implies when to use the tool: whenever a specific BotInstance needs to be enabled or disabled at the XMPP level. However, it does not explicitly mention alternatives or conditions where another sibling tool like ethora-bot-enable-v2 or ethora-bot-instance-diag would be more 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?

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds real behavioral context beyond those: omitting roomJid triggers a fan-out side effect across every room, and the tool depends on the ai-service being live. This scope-expansion warning is exactly the kind of trait an agent needs and the annotations do not convey. No contradiction with 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?

Three dense clauses with zero waste: purpose+endpoint, the roomJid fan-out caveat, and the ai-service prerequisite. The verb and resource are front-loaded, and every sentence earns its place for a 4-parameter tool.

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 flat 4-param tool with no output schema and no nested objects, the description covers the essentials: what it does, the key broadcast nuance, and a runtime prerequisite. The one notable gap is that it never states whether test messages are visible to real room participants or confined to diagnostics — important given the fan-out behavior can send messages into many rooms at once. Minor, but worth having.

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 50% — text and roomJid carry descriptions, while botInstanceId and agentIdOrAddress are bare. The description partially compensates: the endpoint pattern (:idOrAddress, :botInstanceId) clarifies the roles of the two undocumented required params, and the fan-out statement reinforces roomJid's broadcast semantics. But it adds nothing about text and doesn't fully define the two bare params, so it meets the compensation bar only partially.

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 — "Send a test message from a BotInstance" — and pins it with the exact endpoint (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/test-message). This clearly distinguishes it from sibling bot-instance tools (status, diag, leave-chat) and chat-message tools (ethora-chats-message-v2), so an agent can select it without opening any other 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?

The description gives actionable usage guidance: "Omit roomJid to fan out to every room the BotInstance is in" explains the targeted-vs-broadcast decision, and "Requires the ai-service to be running" states a prerequisite. However, it does not explicitly name alternatives or say when not to use this tool versus ethora-chats-message-v2 or other bot-instance tools, so it misses the top bar for explicit exclusion routing.

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?

Beyond annotations (which already signal write/idempotent/non-destructive), the description discloses omitted fields are unchanged, activation is best-effort and depends on a prompt, LLM, and backend AI service, and enumerates auth/error behavior. This is unusually 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?

Four compact sentences front-load the purpose and partial-update behavior, then cover activation, auth/errors, and related tools. No filler 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 17-optional-param update tool with no output schema, the description plus schema gives everything needed to select and invoke it: purpose, update semantics, activation requirements, auth modes, failure modes, and related tools.

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 real cross-parameter meaning: omitted fields are left unchanged, `status:'on'` requires a prompt/LLM/backend service, and `appId` behaves differently by auth mode. It does not enumerate all 17 fields, but the schema already does 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 states a specific action and target ('Configure the AI bot for an app') and lists the setting categories, so an agent can tell it from read-only bot tools. It stays at 4 rather than 5 because it does not explicitly differentiate from ethora-agents-update-v2 or explain the legacy-bot vs agents distinction.

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 clear invocation context: partial update, when `status: 'on'` is viable, the two auth modes, and common error cases. It stops short of explicit when-to-use vs alternative tools, only naming related tools without conditions.

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?

Beyond the `readOnlyHint` annotation, the description discloses important behavioral details: the legacy-only restriction, the 422 failure case for API-created apps, 401/403 error conditions, and the related enable/disable field `widgetPublicEnabled`. This gives the agent a realistic picture of edge cases and expected failures without needing to call the 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 dense but well-structured with clear labels (LEGACY, Auth, Errors, Related) and front-loads the critical scoping information. Every clause adds operational value: endpoint, legacy constraint, alternative, auth prerequisite, error cases, and related configuration. No filler 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 zero-parameter tool with no output schema, the description is complete: it identifies the endpoint, the exact eligibility constraint, error codes, auth requirements, and the related update path. The agent has everything needed to invoke it correctly and anticipate 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?

The input schema has zero parameters and 100% coverage, so there is nothing to document. The description still adds relevant invocation context by specifying the required auth mode. A 4 reflects the no-parameters baseline with useful surrounding setup information.

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 ('read the per-app bot widget config'), names the exact resource ('GET /v2/bot/widget'), and explicitly differentiates itself from the sibling tool `ethora-widget-embed-snippet`. The 'LEGACY' prefix immediately signals its scope, so an agent can distinguish it from the many bot and widget-related 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?

It gives concrete when-to-use conditions: only apps with a legacy aiBot have a config, and API-created apps get a 422. It also provides an explicit alternative (`ethora-widget-embed-snippet`) for the embeddable AI chat widget, plus the required auth sequence (`ethora-app-select` + `ethora-auth-use-app`). This leaves no ambiguity about when to invoke this tool versus its 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond that: it discloses the returned state values, the auth modes and the requirement to match the auth used to enqueue, and the error responses (401/403/404). This goes well beyond the minimal annotation coverage.

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 with no fluff. It front-loads the core purpose, then packs auth and error info, and finally references the related tool. 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?

For a one-shot status fetch, the description covers what it returns (state), the auth constraints, the error cases, and how it relates to the wait tool. With no output schema, this is sufficient for an agent to call it correctly and interpret the result.

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 fully documents both jobId and appId, including their formats and conditions. The description adds no new parameter details beyond what the schema already provides, so the 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 fetches the status and per-room results of a broadcast job by jobId, explicitly calling out that it is one-shot and non-polling. It distinguishes itself from the wait variant by naming it as an alternative, so an agent can immediately tell them apart.

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 says 'one-shot, no polling' and names the blocking wait tool as the related alternative, giving clear guidance on when to use this tool versus waiting. It also specifies auth mode requirements (app-token vs B2B with appId) and the error codes, leaving no ambiguity about prerequisites.

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?

Beyond the annotations, the description discloses important runtime behavior: the job is enqueued asynchronously, it returns a jobId rather than sending immediately, and it specifies auth modes and likely error codes. This is substantial behavioral context that annotations alone do not provide.

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 and async behavior come first, followed by targeting rules, auth, errors, and the related tracking tool. Every sentence contributes useful operational information with 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, the description covers the necessary operational surface: what it does, what it returns, when it is not synchronous, how targeting is restricted, which auth modes are valid, likely errors, and how to track the job. This is sufficient for correct selection and 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 description coverage is 100%, and the schema already documents each parameter and its mutual exclusivity constraints. The description re-emphasizes the exclusive targeting rule and auth-mode behavior but does not add meaningful new semantics 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 names a specific action ('Enqueue an asynchronous broadcast job'), the resource ('posting a message to one or more chat rooms of an app'), and the key output ('returns a jobId'). It also clarifies that messages are not sent synchronously, which distinguishes it from related chat-sending 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 gives clear usage context: asynchronous behavior, exclusive targeting modes, auth requirements, and error conditions. It explicitly points to ethora-wait-broadcast-job-v2 as the tracking tool, though it does not name an alternative for synchronous single-room messaging.

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 goes well beyond annotations (which only declare readOnlyHint and destructiveHint) by detailing error codes (401, 403, 404, 502), auth restrictions (user/B2B, not app-token), and the pagination cursor behavior (nextBefore for older pages). It also mentions the mamUnavailable flag for deployments without archives. This is a high level of 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 a single dense paragraph, but it is well-organized: purpose first, then output format, then identification, then auth, then errors. Every sentence adds value. It could be split into bullet points for readability, but it's not overly long and stays focused.

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 read-only tool with no output schema, the description covers all essential aspects: endpoint, response fields, pagination, room identification, auth modes, and error cases. Nothing an agent needs to successfully call this 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 coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it restates the roomJid format, the optional appId, and the either/or requirement. It does add the output fields and cursor, but that's not parameter-specific. Since the schema already explains parameters well, and the description merely echoes that info, a 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 clear verb ('Read'), resource ('archived messages of a chat room'), and explicitly gives the endpoint path. It distinguishes from sibling tools by focusing on reading history, unlike search or send. 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 provides essential usage context: how to identify the room (via roomJid or chatId+app), supported auth modes, and what the response contains. It does not explicitly contrast with sibling tools (e.g., ethora-messages-search-v2), but the purpose is clear enough that an agent would not confuse it with sending or searching. A slight deduction for not stating 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?

Annotations are minimal (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds rich behavioral details: the broadcast sender attribution, auth mode restrictions (user/B2B, not app-token), specific error codes (401/403/404/422), the MAM dependency for reply detection, and the meaning of `replies` and `historyUnavailable`. This far exceeds the annotation coverage and gives the agent precise expectations.

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 dense but every sentence earns its place: endpoint, attribution, usage example, wait option, reply handling, auth modes, errors, and MAM dependency. It is well-structured, front-loads the core purpose, and does not waste words despite its length.

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 6 parameters, auth complexity, error conditions, and a dependency on MAM, the description covers all essential aspects: room identification, sender override, waiting behavior, auth constraints, error codes, and the reply-detection caveat. No critical information is missing for an agent to call 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%, so the baseline is 3. The description adds value beyond the schema: it explains the relationship between `roomJid` and `chatId`, notes the default for `senderName`, and clarifies the purpose of `waitForReplySec` relative to AI agents. It doesn't add new syntax for `appId`, but the schema already covers it. The addition is meaningful but not exhaustive; hence 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 clearly states the verb 'Post a message' into a chat room, specifies the exact endpoint, and explains the message attribution. It distinguishes itself from siblings by explicitly referencing the invite tool and the use case (seeding/testing a conversation). No ambiguity about what it 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?

Provides explicit usage context: 'seed or test a conversation' and gives a concrete sequence ('right after ethora-agent-invite-to-chat'). Also explains when to wait for replies and mentions the alternative of not waiting. It even lists auth modes accepted and the error scenarios, which helps the agent decide when to call 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?

The description adds substantial behavior beyond annotations: values are stored in memory only, omitted fields are preserved across calls, credentials are per-session, `apiUrl` may be fixed on hosted servers, no auth is required to set auth material, and errors occur only for structural invalidity. This strongly complements the idempotentHint and non-read-only annotations without contradicting them.

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?

Six compact sentences cover action, storage model, env-var alternative, platform constraint, auth requirement, error behavior, and next step. Every sentence earns its place, and the most important operational fact 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 is complete enough for an optional-parameter configuration tool: it explains scope, merging, constraints, auth, error behavior, and the correct next tool. The only minor gap is that no success response/return value is described, though the error statement partially compensates since there is no 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?

Schema coverage is 100%, and each parameter already has detailed descriptions including examples, secret warnings, and mode implications. The tool description adds relevant session-level semantics like merge-on-partial-call, but does not need to restate per-parameter meaning; 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 a specific verb and resource: 'Set the Ethora API URL and credentials for this MCP session.' It clearly differentiates itself from the auth-use siblings by framing configuration as establishing auth material that is later selected by an `ethora-auth-use-*` tool.

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 states when to use this tool versus env vars, notes the hosted-server constraint on `apiUrl`, and gives a direct follow-up instruction: 'Follow with an `ethora-auth-use-*` tool to pick the active mode.' This gives an agent actionable selection and sequencing 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?

Annotations already mark the tool as read-only and non-destructive, and the description adds valuable behavioral context: return shape `{ state, checks, ping, suggestions }`, no auth required, and a rare-throw error model that returns `suggestions` and a `ping.ok: false` block. This exceeds what annotations alone provide.

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: purpose and endpoint in the first, return shape in the second, auth/error behavior in the third. Every sentence carries distinct information, and the most important action 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 tool with one optional, well-schema-documented parameter and no output schema, the description provides the return shape, auth requirements, error behavior, and a sensible default timeout note in the schema. No critical calling information 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?

The single parameter `timeoutMs` is fully described in the schema with default, bounds, and usage guidance. The description does not add parameter-level detail, but schema coverage is 100%, so the baseline 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 identifies a specific action (diagnose the session) and resource (session config plus Ethora API ping), and it specifies the endpoint `GET /v1/ping`. It is unambiguous enough to be distinguished from siblings like `ethora-status` by its config-validation and ping behavior, though it does not explicitly name or contrast an alternative sibling.

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 use case is implied by 'Diagnose the session' and the explanation that it validates config consistency for the active auth mode and pings the API. However, there is no explicit guidance about when to prefer this over alternatives such as `ethora-status` or `ethora-help`, and no when-not-to-use conditions are provided.

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 goes well beyond the annotations by disclosing that the record and stored content are removed, that the action is irreversible, that user-auth is required, and that specific HTTP errors occur. This is exactly the behavioral context an agent needs 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 compact and well-structured: a clear one-sentence operation, followed by auth, error, and related-tool notes. Every sentence provides useful information and there is 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?

For a one-parameter destructive tool with no output schema, this description is complete: it covers action, irreversibility, authentication, error cases, and where to find the required id. An agent has everything needed 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 only parameter, id, already has a complete schema description including how to obtain it. The main description adds the endpoint context but not new semantics beyond the schema. With 100% schema coverage, 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 states a specific verb ('Permanently delete'), a precise resource ('one of the authenticated user's files'), and the identifier mechanism ('by id'). It also includes the endpoint, making the operation unambiguous and clearly distinct from sibling file tools like upload and get.

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 for use: deleting a user file by id, with required auth mode and expected error codes. It also points the agent to ethora-files-get-v2 for obtaining ids. It does not explicitly discuss when not to use the tool, but for a delete operation the guidance is sufficiently 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?

The description adds meaningful behavioral detail beyond the annotations: it specifies the required auth mode, the 401 and 404 error conditions, and the array-vs-single-object return shape. Since readOnlyHint and destructiveHint already cover safety, this extra context is valuable and does not contradict 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?

The description is compact, front-loaded with the primary action, and includes only essential operational details: return shape, auth requirement, and likely errors. No redundant phrasing or filler sentences.

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 read-only tool with one optional parameter, the description covers the core semantics, auth context, error behavior, and the two possible return shapes. With annotations supplying the read-only and openness hints, nothing essential is missing for an agent to call 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%, so the schema already documents the id parameter and its behavior. The description reinforces the omit-to-list vs. provide-to-get semantics, but does not add significantly new parameter-level information 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 tool's dual behavior: list the authenticated user's files or fetch a single file's metadata by id. It uses a specific verb and resource ('List the authenticated user's files, or fetch one file's metadata by id') and is easily distinguishable from sibling file tools like upload and 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?

The description gives clear usage context by explaining when to omit vs. provide the id, which determines whether the tool lists all files or returns one record. It does not explicitly name alternative tools or exclusion criteria, but the optional-id behavior is sufficient for correct selection in most 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?

Description adds substantial behavioral detail beyond the minimal annotations (readOnlyHint false, destructiveHint false): each upload is a new record (no overwrite), base64 encoding, 50MB size limit, and error conditions. It also discloses auth-state requirements, which is critical for correct use. 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 (three sentences) and front-loaded with the primary purpose and scope. Each sentence serves a distinct purpose: core behavior, auth requirement, errors, and related tools. No redundant or vague wording.

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 (multiple files, base64, auth constraints), the description covers preconditions (auth), failure modes (401/413/422), size limits, and the non-overwrite semantics. It includes related tools for follow-up actions. Absence of an output schema is acceptable since the description doesn't need to describe returns, and the description is sufficient 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?

The schema description covers 100% of the parameter `files`, including its sub-properties (name, mimeType, base64) with details like base64 prefix stripping and 50MB limit. The tool description adds no new parameter-specific guidance, so the baseline 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 states a specific verb ('Upload'), resource ('files to the authenticated user's Ethora file storage'), and includes the exact endpoint (`POST /v2/files`). It clearly distinguishes from siblings by noting management via `ethora-files-get-v2` / `ethora-files-delete-v2`.

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