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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses significant behavioral traits: lazy creation of a per-App BotInstance, live XMPP client spawn, and no ai-service restart requirement. It also clarifies that multiple agents can coexist, which is important for expected state changes.

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 multi-sentence but each sentence contributes value: core action, multi-agent behavior, side effects, recipe pointer, and prerequisites. It front-loads the primary action and is not wasteful, though it is slightly longer than the minimum needed.

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?

Covers prerequisites, side effects, usage pattern, and points to a recipe for complex scenarios. It does not explain return values (no output schema) or error handling, but these are not essential for a tool with clear side effects. The description is sufficient 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% with detailed descriptions for each parameter, including preferred chatJid and alias agentId. The description adds no additional parameter-level meaning beyond the prerequisites (agent and room), so it does not elevate the baseline of 3 set by high schema coverage.

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 — 'Invite an Agent into a chat room' — with clear resource and verb, and elaborates on multi-agent coexistence and side effects (lazy BotInstance creation, XMPP spawn). It distinguishes itself from creation tools by explicitly requiring an existing agent and room, which positions it as an invitation step rather than a creation step.

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 prerequisites ('Requires: an agent ... and a room') and usage pattern ('call this tool once per agent'), making it clear when to use. It does not name specific alternative tools, but the context implies this is the invitation action distinct from agent creation or chat creation, and points to a recipe for multi-agent setups.

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 idempotent and open-world; the description adds that it sets specific configuration values and explains the route selection based on auth type. It also clarifies that it is required before widget can answer, which is key context. It does not contradict 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 relatively long but well-structured with sections for preconditions, auth, errors, and related tools. It front-loads the primary purpose and uses clear headers implied by punctuation. While comprehensive, every sentence contributes to the agent's decision-making, so no waste.

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 prerequisites, auth requirements, error codes, and next steps. It also clarifies the distinction between API-created and dashboard-created apps regarding chatJid. Together with the rich input schema, an agent has enough 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 description coverage is 100% and each parameter's description in the schema already explains purpose and defaults (e.g., appId defaults, agentId source, chatJid requirement). The tool description does not add extra semantic meaning beyond what's in the schema, so 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 function: 'Make an agent the app's ACTIVE widget bot' and pinpoints the exact effect (setting App.defaultBotInstanceId and botStatus). It also connects to the consuming endpoint and frames the requirement clearly. This distinguishes it from related tools like invite-to-chat or create-agent because it focuses on activation for widget.

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 preconditions: 'the agent was invited into a room of this app with ethora-agent-invite-to-chat', and it names the sequence of tools. It also specifies auth modes and error scenarios, and points to next steps (widget-embed-snippet). This is thorough guidance for when to use and what is required.

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 it is not read-only and not destructive; the description adds that the source agent remains unchanged, the clone becomes the session's current agent context, and lists specific error conditions (401/403, 404, 422). This goes beyond 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 sentences pack in the core action, endpoint, requirements, auth mode, and error cases with no fluff. Information is front-loaded and every sentence carries 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?

The description covers the operation, side effects, prerequisites, auth, and errors. Without an output schema, it is still complete enough for an agent to invoke the tool correctly 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 schema documents all parameters. The description briefly mentions optional overrides and the agentId/address alias, but adds little beyond the schema's own descriptions. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Duplicate'), resource ('existing saved agent'), and outcome ('new clone becomes the session's current agent context'). It also includes the endpoint and notes the source agent is unchanged, which differentiates it from create/update 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 provides clear context: it requires an existing agent id/address from list or create, and specifies auth prerequisites. It does not explicitly name when-not-to-use alternatives, but the purpose clearly implies cloning an existing agent rather than creating or updating.

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 readOnly=false and openWorldHint=true, and the description adds significant behavioral context beyond them: auth-mode restrictions, backend rejection of app-token mode, agent ownership by app, server-side compilation and rejection of invalid flowsYaml with nothing stored, and the reserved flow name 'start'. 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 dense but well-structured: endpoint and auth constraints are front-loaded, the persona/response-gate concept is summarized, the multi-agent workflow is routed to the right sibling, and the prerequisite is stated at the end. Every sentence earns its place 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?

Given the tool's high complexity — 20 parameters, multi-agent behavior, auth modes, and flowsYaml validation — the description covers prerequisites, exclusions, multi-agent recipe, and backend validation behavior. The absence of an output schema is not a material gap here because the creation behavior and parameter semantics are fully described.

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 cross-parameter meaning by grouping fields into persona settings, LLM config, and response-gate settings, and by connecting responseMode/cooldownSec to room behavior and multi-agent turn-taking. This goes slightly beyond the individual schema descriptions, though the schema already carries the bulk of the 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 opens with a specific verb and resource: 'Create a reusable AI agent (POST /v2/apps/:appId/agents).' It clearly distinguishes the create operation from siblings like ethora-agents-update-v2, ethora-agents-list-v2, and ethora-agent-invite-to-chat by focusing on creation and persona configuration.

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 states when this tool is appropriate: create agents, one per persona, and for multi-agent scenarios create each separately then use ethora-agent-invite-to-chat. It also gives a prerequisite ('Requires: a selected app... or an explicit appId') and an exclusion ('app-token mode is not accepted by the backend'). This is strong usage 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds a consequence for public agents (cross-app invitation) but does not mention side effects on existing visibility or any restrictions. Given annotations are present, the description adds limited extra 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 two sentences with no redundancy. The core action is front-loaded in the first sentence, and the second sentence provides a necessary prerequisite. It is appropriately sized and structured.

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's 'Requires' statement conflicts with the input schema's required field (only visibility is required), potentially leading an agent to omit the id. It also fails to clarify that agentId and agentIdOrAddress are aliases and that only one is needed. Given the low schema coverage, this is a significant gap 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 coverage is only 33% (only agentId has a description). The description explains that an agent id or address is required and where to obtain it, and explains the effect of 'public' visibility. However, it does not clarify the alias relationship between agentId and agentIdOrAddress, nor that only one is needed, and it contradicts the schema by implying an id is required when the schema does not mark it as required.

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 'set' and the resource 'Agent's visibility' with an explicit enumeration of the three allowed values (private | unlisted | public). It also adds a meaningful behavioral note about public agents being invitable cross-app, which helps distinguish this tool from siblings like ethora-agents-update-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 gives a prerequisite by stating that an agent id or address is required and references where to obtain it (ethora-agents-list-v2 or ethora-agents-create-v2). However, it does not explicitly compare with alternative tools like ethora-agents-update-v2 or ethora-agents-activate-v2, leaving some ambiguity about when to prefer 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 already indicate readOnly, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: format=json returns the bundle object directly)Skip and that the bundle can be fed to import for cross-tenant recreation. It does not fully describe the zip return behavior, but this is minor given the 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?

Two compact sentences, with the primary action and endpoint front-loaded, followed by the round-trip purpose and prerequisite sourcing. Every sentence earns its place 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 simple export tool with no output schema, the description covers what the tool produces, how to consume it, and where to get the required identifier. It could mention the zip format behavior more explicitly, but the essential calling context is 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 coverage is 67%, and the description compensates by clarifying that the agent id comes from list/create tools and that json is the preferred format for MCP round-trips. It also reinforces the alias relationship between agentId and agentIdOrAddress via the schema description. This adds meaning above the raw 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: 'Export an Agent as a portable bundle', with the exact endpoint and the round-trip use case. It distinguishes itself from sibling tools by explicitly naming ethora-agents-import-v2 as the counterpart that consumes the exported bundle.

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 guidance on when to use it: to export an agent and later recreate it in another App/tenant via import. It also tells the agent where to obtain the required id/address (from ethora-agents-list-v2 or ethora-agents-create-v2). It does not explicitly list exclusions versus get/clone, but the context is sufficient.

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 declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds genuine behavioral value beyond annotations by disclosing a session-side side effect: 'Also sets this agent as the session's current agent context (no server-side change)' — important because readOnlyHint would otherwise imply zero state change. It also surfaces auth failure (401/403) and 404 semantics, enriching the agent's 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?

Every sentence earns its place: purpose, config contents, session side effect, id source, auth requirements, and error conditions. The core purpose is front-loaded in the first clause, and dense supporting details follow 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 read-by-id tool with no output schema, the description covers the config fields returned (prompt, LLM, RAG settings, visibility), the side effect, prerequisites, auth, and error cases. 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 both parameters (agentId, agentIdOrAddress) are already described in the schema, including 'Get it from ethora-agents-list-v2.' The description's mention of sourcing ids from list/create adds only marginal reinforcement over what the schema states, 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 states a specific verb+resource+scope: 'Fetch one reusable saved agent's full config by id' and enumerates the config contents (prompt, LLM, RAG settings, visibility). This cleanly distinguishes it from the sibling set (list, create, update, delete) since it is the only read-by-id operation.

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

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

Gives explicit prerequisites — 'Requires: an agent id or address from ethora-agents-list-v2 or ethora-agents-create-v2' — plus the auth state (app-token after ethora-app-select + ethora-auth-use-app) and expected error codes. It does not explicitly name when NOT to use it or route to a sibling alternative for the same job, which prevents a 5, but the context is unambiguous.

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 (mutating), idempotentHint=false (non-idempotent), and destructiveHint=false (not destructive). The description adds the endpoint (POST /v2/agents/import), the requirement for a bundle from export, and the optional ownerAppId scoping. It does not describe side effects, error behavior, or what happens on success. Given annotations cover the core behavioral profile, the description adds only modest context, justifying a 3.

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 redundancy. It front-loads the primary purpose and then states the requirement and optional parameter. Every sentence contributes meaning, and the structure is efficient. This is a model of conciseness for a tool with moderate complexity.

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 has a nested bundle object, no output schema, and moderate complexity. The description covers the purpose, prerequisite, and optional scoping, but does not describe the return value (e.g., the imported agent object) or any error conditions. While annotations cover the mutating nature, an agent calling this tool might want to know what it returns. This gap prevents a higher score, but the description is adequate for the core operation, so 3.

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%: the schema already documents 'bundle' as 'The bundle object returned by ethora-agents-export-v2 with format=json. Pass it through unchanged' and 'ownerAppId' as 'Owning App for the imported Agent (defaults server-side)'. The description's mention that the body IS the bundle and the option to scope via ownerAppId adds minimal value beyond the schema. Since schema does the heavy lifting, baseline 3 is correct.

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: 'Import an Agent from a bundle produced by ethora-agents-export-v2'. It identifies the resource (Agent), the source (bundle from export), and the verb (Import). This distinguishes it from siblings like create-v2 (which creates from scratch) and clone-v2, making the purpose unambiguous.

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

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

The description provides clear context: the tool is for importing an agent from an existing export bundle, and it specifies a prerequisite (bundle must be from ethora-agents-export-v2 with json format). However, it does not explicitly mention when not to use this tool or name alternatives (e.g., 'use create-v2 if you don't have a bundle'). It gives context but no explicit exclusions, so a 4 is 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 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 declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds context about what is being modified (SOUL.MD, evolving identity/private notes) and who can call it (operator or the agent itself via ai-service). It doesn't disclose details like whether the append is atomic, how large the fragment can be, or what the response looks like, but the annotations cover the core 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?

The description is two sentences and front-loads the core action ('Append a fragment to an Agent's SOUL.MD'). The second sentence adds relevant context about who can call it and the prerequisite. No wasted words, though the parenthetical '(its evolving identity / private notes)' is slightly redundant with 'SOUL.MD' but still useful for clarity.

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 append operation with 3 parameters and no output schema, the description covers the essential context: what is being modified, who can call it, and where to get the required identifier. It doesn't explain the return value or error cases, but given the simplicity of the tool and the annotations covering the mutation profile, this is adequate but not exhaustive.

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% (only `agentId` has a description). The description itself doesn't explain the parameters beyond the schema. However, the schema is fairly self-explanatory: `append` is the fragment to append, and `agentId`/`agentIdOrAddress` are aliases for the same identifier. The description's mention of 'agent id or address' adds a little context, but it doesn't fully compensate for the undocumented `append` and `agentIdOrAddress` 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 clearly states the action ('Append a fragment to an Agent's SOUL.MD') and identifies the resource (an Agent's evolving identity/private notes). It distinguishes itself from the sibling `ethora-agent-soul-set` by using 'append' vs. the sibling's 'set', though it doesn't explicitly name the sibling. The mention of operator-driven vs. self-edit adds useful context.

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

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

The description provides clear context: it's for appending to an Agent's SOUL.MD, and it notes that the Agent itself can self-edit via the same endpoint when called by ai-service. It also states a prerequisite: requires an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`. It doesn't explicitly say when NOT to use it (e.g., when to use `ethora-agent-soul-set` instead), but the append-vs-set distinction is implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds the requirement of an agent id from specific tools and the alternative-to-append context. However, it does not disclose any side effects beyond replacement (e.g., irreversibility) or permission requirements beyond 'Operator-driven'. Since annotations cover the basic safety profile, the description provides moderate added value.

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 redundant wording. It front-loads the purpose and immediately adds the alternative and requirement. 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 replace operation with no output schema, the description covers the essential aspects: what it does, the alternative, and how to obtain the required agent id. Annotations handle idempotency and destructive hints. It does not mention reversibility or effects on existing content beyond replacement, but given the simplicity and annotation coverage, this is sufficient.

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 67% (2 of 3 parameters have descriptions). The soulMd description 'Replace SOUL.MD contents. Pass empty string to clear.' and agentId description 'Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.' add meaningful semantics. The main description does not elaborate on parameters, relying on the schema. Since coverage is moderate and descriptions are helpful, a 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 clearly states a specific verb ('Replace') and resource ('Agent's SOUL.MD'), and distinguishes it from the sibling tool 'ethora-agent-soul-append' by labeling itself as the alternative to append. This makes the purpose unambiguous and 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?

The description notes it is 'Operator-driven' and 'alternative to -append', giving some context for when to use it over the append tool. It also specifies a prerequisite: an agent id or address from 'ethora-agents-list-v2' or 'ethora-agents-create-v2'. However, it does not explicitly state when NOT to use this tool or compare it to other set/update 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that it's a partial update (only passed fields are updated) and that it requires an existing agent id. It does not contradict annotations. The 'nothing is stored' detail is in the flowsYaml parameter description, not here. The description gives some behavioral context beyond annotations, so a 4 is appropriate.

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, two short paragraphs. It leads with the action and endpoint, then gives common uses and a requirement. No fluff, every sentence adds information. Very concise and structured.

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 the core purpose, common uses, and a prerequisite. It references a quickstart for more details. For a tool with 21 parameters, it doesn't enumerate them (schema does), but it provides enough context to guide usage. The absence of an output schema means return values aren't described, but that's not required. It's reasonably complete for an update tool.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description itself doesn't add parameter-level semantics beyond mentioning common use cases and the requirement for an agent id. It doesn't explain each parameter, but the schema does. Since coverage is high, baseline is 3, and the description adds minimal extra value, so 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 tool updates an existing AI agent, mentions the HTTP method (PUT /v2/agents/:agentId), and notes that all fields are optional for partial updates. It gives common use cases, which helps the agent understand the purpose. While it doesn't explicitly distinguish from every sibling, the name and description are 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 typical scenarios (tuning prompt, switching responseMode, adjusting cooldownSec) and states the prerequisite of needing an agent id from list or create. It references the quickstart for the full recipe. However, it doesn't explicitly state when not to use this tool or when to prefer alternatives like create or delete, so it's not fully explicit.

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

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

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 signal destructiveHint and idempotentHint, and the description adds meaningful behavioral context: 'Clients using that key stop working immediately' and '404 unknown id.' This goes beyond the annotation metadata and helps the agent anticipate the real-world effect and failure mode.

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 short, information-dense lines with no filler. The core purpose is front-loaded, followed by prerequisite, auth, and error info. 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?

This is a single-parameter tool with rich annotations and low complexity. The description covers what the tool does, how to get the required id, auth requirements, immediate impact, and an error case. 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 schema already describes `id` as 'API key id as returned by `ethora-api-key-create` / `ethora-api-key-list`.' The description repeats this prerequisite without adding substantially new parameter semantics, 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: 'Revoke one of the current user's API keys by id.' It clearly scopes the operation to the current user and distinguishes it from related key tools like create and list by the revoke action. The wording is unambiguous and immediately tells the agent what the 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?

The description specifies the prerequisite for using the tool: a key id from `ethora-api-key-list` or `ethora-api-key-create`. It also states auth requirements and a likely error condition. It doesn't explicitly name alternatives or say when not to use it, but the context is clear enough for a revoke 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, it discloses that the tool allocates a fresh appId, sets the caller as owner, counts against the plan limit, returns an app object, and redacts credential fields. These are meaningful behavioral disclosures that help an agent predict side effects and response content.

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: purpose, side effects, return behavior, credential redaction, auth, errors, and related tool. It is front-loaded with the core purpose and structured logically.

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 prerequisites, return shape, redacted fields, error codes, plan-limit side effects, and the relevant alternative tool. There is no critical missing information an agent would need 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?

The input schema already fully documents displayName with a clear description and uniqueness caveat (100% coverage). The description only adds a marginal hint that an invalid displayName yields a 422 error, which does not substantially extend the schema semantics.

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 action and resource: 'Create a new Ethora app (tenant) owned by the currently logged-in user.' It also differentiates from the related server-side provisioning path by naming ethora-b2b-app-create, making its scope 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?

It gives explicit prerequisites (user-auth mode, ethora-user-login first), error conditions that inform when the call will fail, and directs the agent to ethora-app-credentials when an appToken is needed and to ethora-b2b-app-create for server-side provisioning. This is strong when-to-use guidance.

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

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

The description goes well beyond the annotations by disclosing side effects: rooms are listed in `defaultRooms`, `pinned: true` auto-joins new users but not existing users, and the operation returns the new room object including JID. It also specifies auth requirements and error codes (401, 403, 404, 422).

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: purpose first, then behavioral effects, then requirements, auth, and errors. 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?

Even without an output schema, the description states the key return value (new room object including JID), covers all relevant error cases, and specifies prerequisites and ownership conditions. Nothing essential is missing for an agent to invoke this 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 parameters well. The description adds valuable nuance, particularly that `pinned: true` does not add existing users and that `pinned: false` keeps the room opt-in, which enriches the pinned parameter semantics 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 a specific action and resource: 'Create a new chat room (MUC room) inside an app the caller owns.' It also explains the room's lifecycle effect ('listed in the app's rooms (`defaultRooms`)'), which distinguishes it from chat messaging or chat deletion 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 explicit prerequisites: a selected app via `ethora-app-select` or an explicit `appId`, plus a clear distinction between `pinned: true` and `pinned: false` behavior. It does not explicitly name alternative tools or state when not to use this tool, so it falls just short of a 5.

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 readOnly/idempotent annotations, the description discloses that this tool is deliberately the only one returning appToken, that output enters the model's context and client logs, and that the App Secret is never exposed. It also gives the exact return shape, auth expectations, and a full error list. These facts materially change how an agent should invoke and handle results, and they are not captured by annotations.

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

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

The description is long but every sentence carries essential information: purpose, redaction policy, App Secret caveat, requirements, auth, errors. It is front-loaded with the core action and organized into clear labeled segments, achieving high density without redundancy or fluff.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the destructiveHint annotation, the description provides rich behavioral context: permanent deletion, removal of the message archive, revocation of member affiliations, irreversibility, environment-flag gating, and specific 401/403/404 error conditions. This significantly outstrips what annotations alone convey.

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-loads the critical destructive and irreversible nature, and then systematically covers requirements, auth, and errors. Every sentence adds necessary operational information with 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 destructive mutation with no output schema, the description is complete: it covers scope, side effects, prerequisites, auth, ownership, gating, and error codes. Nothing an agent needs to safely and correctly invoke 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 description coverage is 100%, so the schema already documents both parameters well. The description reinforces how to obtain chatJid and mentions ownership constraints, but adds no new parameter-level formats or semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Permanently delete a chat room') and resource ('chat room from an app the caller owns'), and enumerates the concrete consequences: removes the MUC room, message archive, and member affiliations. It also distinguishes this from related tools like ethora-app-delete and ethora-app-create-chat by focusing on chat-room deletion scope.

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 prerequisites (a room from ethora-app-get-default-rooms or ethora-app-create-chat), auth requirements (user-auth mode, active session, ownership), and the gating condition (ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true). It does not explicitly contrast with alternative deletion tools, but the scope and prerequisites make usage conditions 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful detail beyond those annotations: the HTTP method, format-specific return behavior, and the include-section selection mechanism.

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, purposeful sentences with no filler. The endpoint and core behavior are front-loaded, and the prerequisite is cleanly separated at the end.

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 export tool with no output schema, the description covers purpose, parameter semantics, prerequisite, and downstream composition with the import tool. The zip return behavior is not detailed, but the essential information an agent needs 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 coverage is 67%, and the description compensates by explaining the appId prerequisite, the format=json return behavior, and the include syntax with an example. All three parameters receive useful semantic guidance beyond raw schema names.

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: 'Export an App as a portable bundle' with an explicit GET endpoint. It also distinguishes itself from related tools by naming the import counterpart and clarifying format/include 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?

Gives clear usage conditions: requires a selected app or explicit appId, and instructs feeding the result to ethora-app-import-v2. It does not explicitly enumerate when-not-to-use alternatives, but the context is strong enough for an agent to proceed correctly.

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?

Annotations already declare this as read-only and non-destructive; the description adds useful behavioral context: return content (rooms with JIDs/titles), auth mode, and specific error conditions (400/401/403/404). 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 main intent is front-loaded in the first sentence, and the supporting requirements/auth/errors are compactly grouped. Each block earns its place, though the error-code enumeration could arguably be trimmed without losing essential guidance.

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-optional-parameter read tool with no output schema, the description covers the input source, auth prerequisites, failure modes, and the key return fields. The only notable gap is the absence of an explicit distinction from the closely related sibling tool.

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

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

Schema coverage is 100% and the schema already documents the optional `appId` and its 24-char hex format and default behavior. The description adds provenance guidance (where to obtain a valid `appId`) and reinforces the selected-app fallback, which is valuable 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 names a specific verb ('List') and resource ('default chat rooms of a specific Ethora app'), with a clear scoping mechanism (`appId` or currently selected app). It does not explicitly contrast with the similarly named sibling `ethora-app-get-default-rooms`, so it stops short of full sibling differentiation.

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 tells the caller to obtain `appId` from `ethora-app-list` or `ethora-app-create`, states that it may also use the currently selected app, and lists authentication/read-access requirements. It provides clear context but no explicit 'when not to use' or alternative routing versus the sibling 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 mark the operation as non-read and non-idempotent, and the description adds useful behavioral context: the request body is the bundle itself, authentication is B2B/tenant-actor, and domainNameOverride renames the domain. It does not detail side effects or return value, but nothing contradicts 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?

Four short, dense sentences with the core action and endpoint front-loaded; every sentence adds information (action, endpoint format, auth, override behavior, prerequisite). 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 2-parameter import tool with no output schema, the description covers what is imported, where the bundle comes from, how auth works, and the optional override. It could briefly state the outcome or confirm optionality of parameters, but the essential invocation context is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying that bundle is the exported bundle from ethora-app-export-v2 and that the JSON body is the bundle itself, and it reinforces what domainNameOverride does. This is helpful beyond the terse schema property 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?

Description names a specific action and resource: 'Import an App from a bundle produced by ethora-app-export-v2'. It also identifies the HTTP route and body format, leaving no ambiguity about what the tool does; the App-domain scope distinguishes it from import tools for other entities such as ethora-agents-import-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?

States clear prerequisites ('bundle produced by ethora-app-export-v2') and auth context ('B2B / tenant-actor auth'), which tell an agent when this tool applies. It does not explicitly list alternatives or when not to use it, but the App-versus-agent distinction plus the bundle requirement is enough 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 description adds meaningful behavioral details beyond the readOnlyHint annotation: credential fields are redacted, an empty list is returned when the user owns no apps, and 401 errors occur when not logged in. This is rich operational context for an agent.

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 yet information-dense, front-loading the core purpose before covering return shape, redaction, auth, errors, and related tools. Every sentence contributes actionable information without unnecessary elaboration.

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

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

Despite having no output schema, the description explains what the returned array contains, which fields are present, redaction behavior, authentication requirements, and error cases. An agent has everything needed to invoke and interpret this 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 tool has zero parameters and the schema is fully covered at 100%, so there is no parameter burden for the description. The description instead clarifies output fields and behavior, which is the relevant semantic content for this empty-schema 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 states a specific verb and resource: 'List all Ethora apps (tenants) owned by the currently logged-in user.' It clearly distinguishes this from other sibling tools by scoping to owned apps and specifying the returned metadata.

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 states prerequisites ('active session (`ethora-user-login` first)'), error conditions, and points to `ethora-app-credentials` when credential revelation is needed. This gives clear when-to-use and when-not-to-use 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description explains concrete runtime effects: the token stops working immediately, clients still using it get auth failures, and no replacement is issued. It also enumerates auth-related error responses, which is valuable behavioral context not present in 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 most critical information is front-loaded in the first sentence, followed by structured, compact sections for requirements, auth, errors, and related tools. Every sentence adds operational detail with no filler or repetition of annotation 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 destructive, auth-gated mutation with no output schema, the description covers prerequisites, authorization context, failure modes, and relationship to sibling tools. The only omission is the success return value, which is not essential for a tool of this kind and is not expected given no output schema exists.

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%: all three parameters (`tokenId`, `appId`, `timeoutMs`) have descriptions with types, constraints, and defaults. The description reinforces the `tokenId` source and `appId` fallback, but does not add meaning beyond what the schema already provides, 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 opens with 'Permanently revoke an app token by `tokenId`', giving a specific verb, resource, and behavior. It further differentiates itself from siblings by noting that no replacement is issued and explicitly routing revoke-and-replace use to `ethora-app-tokens-rotate-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?

It clearly states the prerequisite ('a token id from `ethora-app-tokens-list-v2`'), the required auth mode (B2B with `b2bToken`), and common error conditions (401/403, 400, 404). It also names the alternative for a revoke-and-replace workflow, leaving no ambiguity about 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?

The description contradicts the `idempotentHint: true` annotation. It states the old token is revoked immediately and the new secret is returned exactly once, which implies a second call with the same `tokenId` cannot be idempotent because the old token would already be revoked. Despite the description richly disclosing revocation semantics, auth, and errors, the contradiction with the annotation forces a score of 1 per the contradiction rule.

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 structured: core action first, then prerequisites, auth/errors, and related tool. Every sentence adds operational value, though the error enumeration makes it longer than strictly necessary. No fluff, but not perfectly minimal.

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, non-read-only operation with no output schema, the description covers everything needed: required inputs, prerequisites, auth mode, expected error codes, the one-time return of the secret, and a pointer to the alternative without replacement. No critical context 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%, so the baseline is 3. The description adds modest context by sourcing `tokenId` from the list tool and noting `appId` defaults to the selected app, but these only reinforce schema text without adding substantial new semantics beyond it.

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+resource combination: 'Rotate an app token: revoke an existing token and issue a replacement in one step.' It clearly differentiates itself from the related revoke sibling by noting it performs revocation with a replacement, while pointing to `ethora-app-tokens-revoke-v2` for revoke-without-replacement.

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 when-to-use context: 'in one step,' requires a token id from `ethora-app-tokens-list-v2`, and specifies B2B auth mode prerequisites. It also names the alternative tool (`ethora-app-tokens-revoke-v2`) and lists concrete error conditions, leaving no ambiguity about when and how 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: partial-update semantics ('omitted fields are left unchanged'), the ownership requirement, and the specific error conditions. It also clarifies that botStatus changes do not alter the bot's configured prompt or sources. The only minor gap is that it doesn't describe the response body, but with no output schema and a mutation tool, the error/ownership context is the more important 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 compact and front-loaded: the first sentence states the action and scope, the second states the partial-update semantics, and the remaining lines pack prerequisites, auth, and errors into a scannable block. Every sentence earns its place; there is no filler or repetition of schema 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 mutation tool with 7 parameters, full schema coverage, and no output schema, the description covers everything an agent needs to call it correctly: what fields can be updated, partial-update behavior, how to obtain the appId, auth requirements, ownership, and error semantics. The sibling list includes create/delete/select tools, and the description explicitly routes the agent to the right source for appId. Nothing critical 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%, so the schema already documents every parameter. The description adds meaning beyond the schema by naming the core mutable fields up front, explaining the partial-update behavior, and clarifying the appId default ('defaults to the app most recently passed to ethora-app-select'). It also flags appDescription as a deprecated alias, which is not obvious from the schema alone. The description doesn't repeat every schema detail, which is appropriate given full coverage.

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 ('Update') and resource ('mutable fields on an app the caller owns'), then enumerates the exact fields (displayName, domainName, appTagline, primaryColor, botStatus). It also states the partial-update semantics, which distinguishes it from create/delete siblings. An agent can tell this apart from ethora-app-create and ethora-app-delete without opening the 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 explicitly states the prerequisite ('Requires: an appId from ethora-app-list or ethora-app-create'), the auth mode ('user-auth mode, active session'), and the ownership condition ('the caller must own the app'). It also enumerates the error conditions (401/403/404/422), which tells the agent when the call will fail and how to react. This is explicit when-to-use guidance with no ambiguity.

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?

The description discloses a specific failure mode (422 BOT_NOT_INITIALIZED on clean apps), the precondition of a legacy bot, and a clear limitation. Annotations only say readOnlyHint=false and destructiveHint=false, so the description adds substantial 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 front-loaded with the core purpose and the critical 422 caveat, then follows with a 'Requires' section. It is somewhat long and repeats the alternatives to the Agents API in both the NOTE and the Requires section, which costs a small amount of conciseness.

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 tells an agent when the tool is valid, what precondition must be met, what error to expect otherwise, and exactly which sibling tools to use instead. This is complete enough to invoke the tool correctly in the B2B 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 input schema covers both parameters (appId and botTrigger) with descriptions at 100% coverage, so the structured data already carries the semantic load. The tool description does not add any parameter-level detail beyond what the schema provides, which matches the baseline for high schema coverage.

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 verb and resource: 'Enable the LEGACY per-app aiBot (B2B auth)'. It clearly distinguishes this tool from the v2/Agents family by emphasizing legacy-only scope and calling out the forward path via 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 description gives explicit when-to-use and when-not-to-use guidance: it works only for apps that already have a legacy dashboard-created aiBot, and API-created apps should use ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2 instead. It also names ethora-b2b-app-bootstrap-ai as an alternative for the forward 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?

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds meaningful beyond-annotation context: disabling preserves the configured prompt/LLM/RAG and activated agent, so re-enabling restores behavior. It also clarifies auth modes and error responses. It doesn't cover what happens to the bot's chat history or whether the effect is immediate, but the core behavior is 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?

The description is well structured and front-loaded: main effect first, then prerequisites, auth, errors, and related tool. Every sentence serves a purpose; there is no fluff. It is concise given the amount of context it provides (prerequisites, alternative, auth, errors).

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 mutation tool with one parameter and annotations already covering safety and side-effect hints, the description covers all necessary context: what the tool does, when to use it, prerequisites, alternative paths, auth, error codes, and reversal. No output schema needed. An agent has enough information 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% because the sole parameter `appId` is fully described in the input schema, including format and mode-specific behavior. The description reinforces the appId requirement in B2B mode but adds no new semantic meaning beyond the schema. Since schema does the heavy lifting, 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 states a specific verb and resource: "Turn the AI bot off for an app (sets bot `status: "off"`)". It explains the effect (stops responding) and distinguishes from sibling tools like `ethora-bot-enable-v2` and the agent toolchain by noting it targets legacy per-app aiBots only. This makes the purpose unambiguous.

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

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

It explicitly states when to use this tool: for an app with a legacy per-app aiBot (dashboard-created). It also gives the alternative path for API-created apps (`ethora-agents-create-v2` → `ethora-agent-invite-to-chat` → `ethora-agents-activate-v2`) and notes the related `ethora-bot-enable-v2` to reverse. Auth modes and error codes are also covered, so the agent knows exactly when and how 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds beyond that by disclosing the 422 BOT_NOT_INITIALIZED failure mode and the legacy-only prerequisite, which are critical for an agent to predict behavior before calling.

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

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

The description is front-loaded with the core purpose and then provides error/alternative context. It is somewhat lengthy and slightly repetitive ('Valid for apps...' and 'Requires: an app...'), but each sentence carries useful information.

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

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

For a two-parameter, fully schema-documented tool with annotations, the description is complete: it covers prerequisites, failure modes, auth modes, and alternatives. An agent can decide whether to call this tool and how to interpret a likely error without additional 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?

Schema description coverage is 100%, so the baseline is 3. The description adds auth-mode context and the legacy-app requirement, but it does not elaborate on appId or trigger 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?

States a specific action ('Enable the LEGACY per-app aiBot'), names the resource, and clarifies the scope via auth modes. It also differentiates itself from the Agents API alternative by naming the exact conditions under which that alternative applies.

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 when the tool works ('apps that already have a legacy aiBot'), when it fails with 422 BOT_NOT_INITIALIZED, and which alternative tools to use instead (ethora-agents-create-v2, ethora-agent-invite-to-chat, ethora-agents-activate-v2, ethora-b2b-app-bootstrap-ai). 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: it discloses auth requirements (app-token vs B2B with explicit appId), error semantics (401/403 wrong auth, 404 unknown appId), and the legacy-vs-API-created app distinction. It doesn't describe pagination or return format, but for a single-resource read with no output schema, the disclosed behavior is strong.

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 purpose and resource are in the first sentence, followed by a terse prerequisite, an alternative route, auth/error notes, and a related tool. Every sentence earns its place; there is no filler or repetition of schema 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 single-parameter read-only tool with rich annotations and 100% schema coverage, the description is complete. It covers prerequisites, auth modes, error conditions, the legacy-vs-new distinction, and the related update tool. The absence of an output schema is not a gap because the description enumerates the returned fields. Nothing an agent needs to call 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?

Schema description coverage is 100%, so the schema already documents the single appId parameter well. The description adds meaningful context beyond the schema: it explains when appId is required (B2B mode), when it is ignored (app-token mode), and how it relates to ethora-app-select. This goes beyond the schema's own description and helps an agent decide whether to pass the parameter.

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 ('Read') and a precise resource ('current AI bot configuration for an app'), then enumerates the exact fields returned (status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config). It also distinguishes itself from the ethora-agents-* family by explicitly naming the legacy per-app aiBot scope, so an agent can tell it apart from sibling tools without opening 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 gives explicit when-to-use guidance: it applies only to apps with a legacy dashboard-created aiBot, and it explicitly routes API-created apps to the alternative sequence (ethora-agents-create-v2 -> ethora-agent-invite-to-chat -> ethora-agents-activate-v2). It also states auth modes (app-token or B2B with explicit appId) and names the related update tool (ethora-bot-update-v2). This is exemplary 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context: it returns live XMPP/ai-service status and recent activity, and it requires a bot instance id from a specific sibling tool. It doesn't describe rate limits, pagination, or failure modes, but for a read-only diagnostic tool the annotations plus the description are 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?

Two sentences with no filler. The first sentence states the action, endpoint, and return value; the second gives the prerequisite and source of the required parameter. Every sentence earns its place and 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 read-only diagnostic tool with strong annotations and a clear endpoint, the description is nearly complete. It explains what the tool returns, where the required parameter comes from, and the alias relationship between agentId and agentIdOrAddress. It doesn't describe the output schema, but no output schema exists and the description's mention of 'live XMPP/ai-service status and recent activity' gives the agent enough to 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 only 33%, so the description must compensate. It does: it explains that botInstanceId comes from ethora-bot-instances-list, and it clarifies the agentId/agentIdOrAddress alias relationship ('either name is accepted, pass whichever you have'). This adds real meaning beyond the bare schema fields, though it doesn't fully document all three 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 states a specific verb ('Diagnose'), a specific resource ('a specific BotInstance for an Agent'), and the exact endpoint. It also names the return value ('live XMPP/ai-service status and recent activity for troubleshooting'), which clearly distinguishes it from sibling tools like ethora-bot-instance-status or ethora-bot-instance-test-message.

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 when to use the tool: troubleshooting a bot instance, and it explicitly states a prerequisite ('Requires: a bot instance id from ethora-bot-instances-list'). It doesn't explicitly name alternatives or say when not to use it, but the prerequisite and troubleshooting purpose provide enough guidance to route an agent correctly.

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, covering the safety and mutation profile. The description adds context beyond annotations by stating the endpoint uses POST and that it is the inverse operation, which clarifies the behavioral relationship to invite-to-chat. It doesn't contradict annotations; it enriches them with the 'undo' semantic.

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, each earning its place. The action is front-loaded, the endpoint is included, and the relationship plus prerequisite are stated concisely. No filler or redundant 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 destructive action with no output schema, the description covers the core purpose, the inverse relationship, and how to obtain the required botInstanceId. It doesn't describe the response format or error cases, but those are not expected without an output schema. Given the tool's simplicity and the annotations covering safety, this is adequately 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 50%, with chatJid and agentId described in the schema, but botInstanceId and agentIdOrAddress lack descriptions. The description compensates by indicating that botInstanceId comes from ethora-bot-instances-list, which is helpful but doesn't fully clarify the other parameters. Since schema already covers chatJid, the description adds some value for botInstanceId but not enough to fully offset the coverage gap.

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?

Clearly states the action: 'Remove a BotInstance from a chat room' with a specific verb and resource. It names the HTTP endpoint and explicitly identifies itself as the inverse of ethora-agent-invite-to-chat, distinguishing it from that sibling. The purpose is unambiguous and differentiates the tool from its peers.

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 when-to-use guidance by stating it is the inverse of ethora-agent-invite-to-chat, implying it should be used to undo an invitation. It also specifies the prerequisite (a bot instance id from ethora-bot-instances-list) and how those instances are created, giving the agent concrete steps to gather required inputs. This covers both context and 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 declare read-only, idempotent, open-world, and non-destructive traits. The description adds meaningful context by stating the default appId filter and the dependency on having an invited agent, which explains why the list might be empty. This goes 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, front-loads the core purpose, and then provides filter and prerequisite details without any fluff. 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 simple list operation with three optional parameters and no output schema, the description covers the main purpose, filtering behavior, and a critical prerequisite. It omits details about return format or pagination, but given the annotations and simplicity, this is adequate.

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% (only agentIdOrAddress has a description). The description clarifies that appId defaults to the caller's app and that both appId and agentId are filters, adding some value. However, it does not elaborate on the relationship between agentId and agentIdOrAddress beyond what the schema already says, so the compensation is partial.

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 ('List BotInstances') and resource, clearly distinguishing it from related tools like ethora-agents-list-v2 or ethora-bot-get-v2. It also mentions filters, but does not explicitly name sibling tools for differentiation, which keeps it just short of a 5.

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

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

The description gives a clear prerequisite (an invited agent must exist) and explains the default appId behavior, which implies when the tool is useful. However, it does not explicitly contrast with alternatives like ethora-bot-instance-status or ethora-bot-get-v2, leaving some room for ambiguity.

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 declare readOnlyHint=true, yet the description clearly describes a state-changing operation: 'Turn a specific BotInstance on or off' with detachment and re-spawning behavior. This is a direct contradiction, so the description provides misleading context about the tool's 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, front-loaded with the main action and effect, followed by the necessary prerequisite. No filler or repeated schema information.

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

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

For a two-parameter toggle with an enum, the description provides the essential invocation context: what the action does and where to get the ID. However, the readOnlyHint annotation directly conflicts with the described behavior, and there is no output schema or mention of response/error behavior, leaving some ambiguity for an agent.

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 does: botInstanceId is tied to a specific source tool (`ethora-bot-instances-list`), and the status values 'on'/'off' are given behavioral meaning via detach and re-spawn. This adds real value beyond the raw 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 uses a specific verb and resource: 'Turn a specific BotInstance on or off.' It also explains the operational effect of each state ('Off detaches it from XMPP; on re-spawns the XMPP client live'), which clearly distinguishes this toggle tool from siblings like list, diag, or leave-chat.

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 and a prerequisite: the bot instance id must come from `ethora-bot-instances-list`, and instances are created by `ethora-agent-invite-to-chat`. It does not explicitly state when not to use this tool or name alternatives, but the source-of-id guidance is practical and sufficient for a simple toggle.

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