ethora-mcp-server

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

Beyond the annotations, the description discloses meaningful behavioral details: which route is used with user auth, the fallback to the app-token route, the required bot instance precondition, auth requirements, and specific 404/403 error conditions. It also names the side effects it sets on the app record. These details add real value beyond the structured fields.

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

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

The description is longer than average, but it is front-loaded with the core purpose and follows with preconditions, auth, errors, and related tools. The main redundancy is that the invite precondition is stated twice in the 'Preconditions' and 'Requires' paragraphs, which prevents a perfect score.

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 still covers the essential invocation context: prerequisites, required setup chain, auth mode, fallback behavior, and error cases. Combined with complete parameter documentation in the schema, an agent has enough information to select and call 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?

Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description does not add parameter-level meaning beyond what the schema provides, such as details about `chatJid` or the alias relationship, 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 starts with a specific verb and resource: making an agent the app's ACTIVE widget bot, and names the concrete setting `App.defaultBotInstanceId` with `botStatus: on`. It also explains the downstream effect on `POST /v2/widget/sessions`, which cleanly distinguishes this activation tool from sibling tools like `ethora-agent-create` or `ethora-agent-invite`.

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

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

The description gives strong context for when the tool is needed: it is required before an embedded widget can answer on an API-created app. It also gives preconditions and a related-tool sequence (`ethora-agent-create` -> `ethora-chat-create` -> `ethora-agent-invite`), plus next steps. It lacks an explicit 'when not to use' statement, so it is just short of a perfect score.

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?

Goes beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) by disclosing auth-mode constraints — app-token mode is rejected by the backend — plus ownership/homing semantics ('belongs to your account', 'homed in that app'). It does not cover duplicate-name/slug behavior or the shape of the created resource, which matters for a non-idempotent create.

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

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

Front-loads what the tool does and the endpoint, then moves to auth modes, then to alternatives and prerequisites. Every sentence carries information, though the final 'Requires:' paragraph could be tightened.

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 20-parameter, zero-required-parameter create tool with no output schema, the description supplies prerequisites, auth modes, ownership, and the multi-agent recipe. The one gap is that it never says what the call returns (e.g. the new agent's id), which the caller needs before inviting or updating it.

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

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

Schema description coverage is 100% and the schema already documents all 20 fields in detail, so the baseline is 3. The description adds useful framing by grouping the fields into 'persona' vs 'response-gate settings' and calling out `responseMode`/`cooldownSec` interplay, but no syntax or format beyond the schema.

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

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

States a specific verb+resource ('Create a reusable AI agent') and even names the backing endpoint. It distinguishes itself cleanly from siblings by contrasting with `ethora-agent-update`, `ethora-agent-clone`, and `ethora-agent-invite` in the same paragraph.

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

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

Explicitly routes the agent: use this for one persona, repeat for multi-agent scenarios, then `ethora-agent-invite`; or start from a public template via `ethora-agent-list { visibility: "public" }` + `ethora-agent-clone`; and points at the `ethora-agents-quickstart` prompt. Prerequisite is stated ('a selected app ... or an explicit appId').

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

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

Beyond the annotations, the description discloses meaningful side effects: it lazily creates a per-App BotInstance if one does not exist, spawns the XMPP client live, and requires no ai-service restart. This is exactly the kind of behavioral context annotations alone do not provide.

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

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

The description is information-dense and well structured: purpose, multi-agent behavior, side effects, recipe pointer, and prerequisites. Every sentence earns its place, 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 side-effectful tool with no output schema, the description covers prerequisites, side effects, and usage pattern well. It could be slightly more complete by stating what successful invocation returns or confirms, but the essential information needed to call it correctly 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?

The input schema already documents all 5 parameters with 100% coverage, so the description does not need to re-explain them. It adds only contextual hints like 'in the selected app' and 'call this tool once per agent,' which is acceptable but not a substantial addition 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 opens with a specific verb and resource: 'Invite an Agent into a chat room.' It also clarifies the unique behavior that multiple agents can coexist and that this action is separate from creating agents or rooms, clearly distinguishing it from sibling tools like ethora-agent-create and ethora-chat-create.

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

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

The description gives clear usage context: call it once per agent, and it explicitly states prerequisites ('Requires: an agent... and a room... in the selected app'). It does not explicitly contrast it with alternatives or state when not to use it, but the context is strong enough for an agent to route 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 readOnly/idempotent/non-destructive, and the description still adds material context beyond them: auth requirements (user session or B2B token), error semantics (401/403 wrong auth), empty-list behavior, and the shape of returned fields (ids, names, owner, visibility, categories, config).

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 core listing behavior and the appId switch are front-loaded, and every clause carries information. It is dense with parenthetical endpoints and error codes, which is slightly heavy but not redundant.

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 list tool with no output schema, the description covers scoping, the account-vs-app ownership nuance, auth, error behavior, and return fields — everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 100%, so the schema already explains limit, offset, category, and visibility. The description still adds value on appId by noting it requires app management rights and that B2B tokens always use the app-scoped form, but it does not add anything for the remaining 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?

States a specific verb and resource ('List AI agents') plus the backing endpoint (GET /v2/agents), and immediately distinguishes the appId-scoped variant (GET /v2/apps/:appId/agents). It also clarifies the account-level ownership model, so an agent won't confuse this with per-app listing 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?

Explicitly states the default behavior (own agents plus public), the condition that changes it (pass appId, which requires app management; B2B tokens always use this form), and routes public-agent use to the named alternatives ethora-agent-try and ethora-agent-clone, noting they cannot be edited here.

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 cover the safety profile (destructiveHint=true, idempotentHint=true), but the description goes well beyond them: it explains that passed fields are overwritten and old values are unrecoverable, advises confirming prompt/name/settings changes with the user, and discloses the 403 ownership failure mode. That is exactly the kind of operational context annotations cannot encode.

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 critical destructive-behavior warning is front-loaded, and the second paragraph cleanly handles prerequisites and authorization. Slight redundancy ('Overwrites the fields you pass' vs. 'only what you pass is updated') and the endpoint path add minor noise but no real bloat.

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 21-parameter mutation tool with no output schema, the description covers everything an agent needs to call it safely: destructive/partial-update semantics, ownership/auth requirements, and a pointer to external authoring docs (doc:agent-flows) for the complex flowsYaml field. Nothing material is missing.

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

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

Schema coverage is 100%, so the per-parameter docs already carry the load and baseline is 3. The description still adds value by calling out specific parameters with rationale (prompt for turn-handoff, responseMode for multi-agent turn-taking, cooldownSec), nudging an agent toward the right fields for common tasks.

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

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

States a specific verb and resource ('Update a saved AI agent') and even anchors it to the endpoint PUT /v2/agents/:agentId. An agent can trivially distinguish this from siblings like ethora-agent-create, ethora-agent-list, and ethora-agent-activate.

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 names concrete use cases (tune prompt after a test run, switch responseMode for turn-taking, adjust cooldownSec) and points to the ethora-agents-quickstart prompt for the full recipe. It also spells out prerequisites (agent id/address from list or create) and the ownership constraint with an explicit alternative: clone an un-owned agent and update the copy instead.

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?

Even though annotations already indicate this is a write operation, the description adds materially useful behavioral context: counts against plan limit, allocates a fresh appId, sets ownership, returns redacted credentials, and requires a separate reveal call for the appToken. It also specifies auth and error behavior. No contradiction with the annotations is present.

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

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

The description is dense but well organized: core behavior first, then auth, errors, and alternatives. Every sentence contributes agent-relevant information, with no filler or tautological repetition of the title.

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 the return shape, the redaction behavior, the follow-up tool for credentials, auth prerequisites, failure modes, and the related server-side alternative. An agent has enough context to select and invoke the tool correctly without further lookup.

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 fully defines displayName and its meaning. The description adds only the indirect detail that an invalid displayName yields a 422 error, which is marginal. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description uses a specific verb and resource ('Create a new Ethora app (tenant)'), states the concrete outcome (allocation of a fresh 24-char hex appId, caller set as owner), and describes the return value. It also distinguishes this user-facing creation tool from the related server-side ethora-b2b-app-create, making sibling differentiation 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 explicitly states the required auth mode and prerequisite ('user-auth mode, active session (ethora-user-login first)'), gives error conditions (401, 402/403, 422), and names the alternative for server-side provisioning (ethora-b2b-app-create). This is explicit when-to-use guidance with a clear exclusion.

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 the safety profile (readOnly, idempotent, non-destructive), and the description still adds real behavioral value: credential field redaction (appSecret, tenantSecret, appToken, passwords), the exact 401 failure mode, and the empty-list outcome when the user owns no apps.

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 tight sentences, front-loaded with what it lists and scoped to ownership, then results, then auth/errors/related tools. No filler, every clause carries information.

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

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

With no output schema, the description compensates fully by naming the returned fields (appId, displayName, domainName, ownership, bot-status), the redaction policy, the error case, and the related reveal/update/select tools. An agent has everything needed to call it and act on the result.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing parameter-level the description needs to explain beyond routing the resulting appId into follow-up tools, which it already does.

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 ('List all Ethora apps (tenants)') and narrows scope to apps owned by the current user, which separates it from ethora-app-create/update/select. The parenthetical '(tenants)' even disambiguates the domain term.

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 activation context: user-auth mode with an active session and 'ethora-user-login first' as a prerequisite. It also routes downstream ('feed appId into ethora-app-update / ethora-app-select'). It stops short of an explicit when-not or a named sibling to use instead, so 4 rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: 'Changes nothing on the server,' re-callable to switch at any time, 24-hour persistence for the signed-in account on the hosted server, no auth required, and no validation errors (404 surfaces only on the first app-scoped call). This is exactly the kind of behavioral detail annotations cannot carry.

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 key fact (session-only, set app context) is front-loaded and every sentence carries information. It is dense and slightly run-on in the later clauses about hosted-server persistence and authMode defaulting, but nothing is wasted.

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

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

With no output schema, the description still covers the full picture: session vs. server scope, auth requirements, error behavior, persistence duration, and interaction with ethora-app-create and ethora-auth-mode-set. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-parameter interaction that the schema does not state: providing appToken defaults the auth mode to app-token unless authMode overrides, and it stores currentAppId/appToken. That interplay between the optional params is genuine added value.

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

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

States a specific verb and resource: 'Set the current app context for this session.' The opening 'Session-only: remembers which app later calls refer to' immediately distinguishes it from server-mutating siblings like ethora-app-create or ethora-app-update.

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

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

Explicitly says when to use it ('so app-scoped tools can omit their appId argument') and when it is unnecessary ('ethora-app-create selects the new app by itself, and an account with exactly one app has it selected automatically'). It also names the related tool it pairs with (ethora-auth-mode-set), giving the agent clear 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 flag destructive and idempotent, but the description goes well beyond them: it warns that previous values are not kept and cannot be restored from the API, clarifies the partial-update semantics (omitted fields unchanged), and enumerates auth mode plus concrete error codes (401/403/404/422) with a validation example. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the destructive warning, then the field list, then requirements/auth/errors — a sensible ordering for a mutation tool. Some content (error codes, per-field format rules) duplicates the schema, which is mild redundancy rather than bloat.

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 7-parameter mutation with no output schema and no required fields, the description covers irreversibility, partial-update behavior, ownership requirement, auth mode, and failure modes. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the botStatus vs. prompt distinction and the appDescription deprecation note. The description's field list largely restates that; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Update mutable fields on an app the caller owns') and enumerates exactly which fields are mutable (displayName, domainName, appTagline, primaryColor, botStatus). The scope is distinct from siblings like ethora-app-create and ethora-app-list, so an agent can route 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?

Gives real usage context: confirm changes with the user first, and the `appId` must come from `ethora-app-list` or `ethora-app-create`. It also acknowledges the implicit app from `ethora-app-select`. It stops short of an explicit when-not or a named alternative tool, so it is strong but not fully 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?

The description goes far beyond the annotations by explaining defaultRooms listing, pinned auto-join behavior for new users, the opt-in default, return value with JID, authentication mode, ownership requirement, and specific error codes. This gives an agent a rich behavioral model without needing to call the tool blindly.

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 appropriately sized: it front-loads the core purpose, then covers behavioral effects, return value, prerequisites, and errors without wasted 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 create operation with no output schema, the description is complete: it states what is created, side effects, auth requirements, error cases, and what the caller receives back. An agent has enough information to invoke the tool correctly and anticipate failures.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: every created room is listed in defaultRooms, pinned:true does not add existing users, and pinned:false keeps the room opt-in. These nuances complement the schema definitions rather than merely repeating them.

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 ('Create a new chat room (MUC room)') and the resource scope ('inside an app the caller owns'). It clearly distinguishes this tool from siblings like ethora-message-send and ethora-chat-history by focusing on room creation.

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

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

The description gives clear usage context by requiring a selected app or explicit appId and stating the ownership prerequisite. It does not explicitly name alternatives or when-not-to-use cases, but no sibling tool performs the same room-creation function, so the guidance is adequate.

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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral depth: pagination order ('newest last'), the nextBefore cursor, accepted vs rejected auth modes ('app-token mode is not accepted'), and specific error semantics including MAM_READ_FAILED / mamUnavailable. This far exceeds what the annotations 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?

Front-loads the core purpose before endpoint, return shape, prerequisites, auth, and errors. It is dense but nearly every clause carries distinct, useful information; only the raw endpoint path borders on redundant detail.

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

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

With no output schema, the description compensates by describing the return shape (from, nick, body, ts in ms, nextBefore cursor) and enumerating auth and error cases. An agent has everything needed to invoke and interpret the result 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%, so all five parameters (including roomJid format and the before cursor) are already documented in the schema. The description mostly restates the roomJid/chatId relationship and confirms appId is optional rather than adding new syntax or constraints beyond the schema, warranting the baseline 3.

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

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

States a specific verb+resource ('Read the archived messages of a chat room') and even supplies the underlying endpoint. It is clearly distinguishable from the sibling ethora-message-send (write) without opening any schema.

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

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

Gives the prerequisite ('a room in the selected app' via ethora-chat-create) and names ethora-app-select for app selection, which routes the agent well. It does not explicitly compare against an alternative read tool (none exists), so it stops just short of full when/when-not guidance.

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

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

The annotations carry only basic hints, so the description carries the behavioral burden. It discloses anonymous operation, account attribution when signed in, redaction of credential-shaped values, automatic attachment of recent failures, and 422/429 error conditions. This goes far beyond what the structured fields provide, with no contradiction.

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

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

Dense but efficient: every sentence carries a usage trigger, a constraint, or an error condition. The core purpose is front-loaded, and the labeled auth/error block is easy to scan. Nothing feels redundant or promotional.

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

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

For a low-risk feedback submission tool, this covers the decision triggers, parameter guidance, auth behavior, redaction, and failure modes. No output schema is present, but an agent already knows enough to call the tool correctly. There is no meaningful gap that would cause a misinvocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining why `includeRecentErrors` matters (server-side log join) and that credential-shaped values in attached context are redacted. It partially duplicates the schema text, but the redaction and error-behavior clarifications push it above baseline.

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

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

States an unambiguous verb and resource ('Send feedback about Ethora') and enumerates the report types ('does not work, behaves differently, missing, badly documented'). This clearly distinguishes it from the dozens of operational sibling tools in the list.

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

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

Explicitly instructs the agent to prefer this tool over guessing or silently giving up when a tool fails, and contrasts it with a web form for server-side traceability. It also explains when it is useful even without authentication. The triggers and exclusions are clear enough that an agent can decide when to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: no auth required, no API calls made, and effectively no error modes. Return shape (recipes/next calls) is only implied.

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

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

Two tight blocks: one sentence of purpose, then a compact Auth/Errors/Related line. Front-loaded and waste-free, though the Auth/Errors/Related shorthand is slightly compressed.

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-required-parameter, read-only helper with no output schema, the definition covers purpose, auth, error behavior and follow-up routing. It could state more concretely what the response contains (recipe ids, next-call list), but nothing needed 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 the single `goal` enum carries an exhaustive per-value explanation, so the schema does the heavy lifting. The description only gestures at the same behaviors ('based on current session state'), adding little beyond it; baseline 3 applies.

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

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

States a specific role (task-oriented orientation for this MCP server) plus concrete content: explaining the three auth modes and recommending next tool calls and recipes. It is clearly not a status/CRUD tool, though it never explicitly contrasts itself with ethora-status, the nearest sibling.

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

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

Gives clear context for invocation (recommendations inferred from current session state) and routes follow-up work by saying a recommended recipe id should be passed to `ethora-recipe-run`. No explicit when-not-to-use or statement of where `ethora-status` is preferred instead.

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, etc.), the description discloses specific behavioral traits: auth modes accepted/rejected, error codes (401, 403, 404, 422), the MAM dependency where `replies` becomes null and `historyUnavailable` becomes true, and the wait/reply semantics. This significantly exceeds 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 longer than average but well-structured into purpose, usage, prerequisites, auth, errors, and reply-detection. Each sentence carries distinct information and there is no fluff or repetition. It is front-loaded with the core action and use case.

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 covers return behavior (`replies`, `historyUnavailable`), errors, auth requirements, prerequisites, and room identification. For a 6-parameter tool with this complexity, 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%, so baseline is 3. The description adds meaning beyond schema by explaining room identification via `roomJid` vs `chatId` and the relationship to `ethora-chat-create`'s return value, the `senderName` override, and `waitForReplySec`'s effect on `replies`. This enriches rather than repeats schema details.

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

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

The description explicitly states 'Post a message into a chat room of an app' with a specific HTTP route and 'targeting one room', making the action and resource clear. It distinguishes this from siblings like ethora-chat-create and ethora-chat-history by focusing on message posting, not room creation or reading history.

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 when-to-use guidance ('Use it to seed or test a conversation, e.g. right after ethora-agent-invite') and lists prerequisites (`ethora-chat-create`, `ethora-agent-invite`). It does not state a 'when not to use' or name an alternative sending tool, but the context is clear and actionable.

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?

Goes well beyond the annotations by disclosing async indexing semantics ('content becomes queryable once indexing finishes'), the 50MB cap, base64 encoding expectations, auth modes, and a full error map (401/403/404/413/422). Annotations already cover safety/idempotency; the description adds the operational behavior an agent needs.

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

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

Purpose is front-loaded in the first sentence, followed by clean Requires/Auth/Errors/Related blocks. Dense with parenthetical detail, but it is organized and nearly every clause carries actionable 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 mutation tool with no output schema, the description covers the async lifecycle, auth requirements, default-agent routing, and error codes, which is everything an agent needs 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 description coverage is 100%, so the baseline is 3. The description restates constraints (1-5 files, base64, 50MB) that the schema already documents, adding only marginal framing rather than new parameter meaning.

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 (upload documents into an agent's knowledge base) with scope qualifiers: 1-5 files, PDF/text, base64, 50MB each. It also distinguishes itself from the legacy variant, so an agent can tell the two apart without opening a 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?

Gives explicit prerequisites ('Requires: a selected app (ethora-app-select) or an explicit appId') and names related tools (list/delete). It does not state when NOT to use this tool, so it stops just short of full 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?

Goes well beyond the annotations: it discloses that existing documents are kept and nothing is deleted, the 409 refusal on already-indexed URLs unless force is set, the exact return shape, the done:false budget-exhausted caveat, auth modes, and specific error codes (401/403, 403 AGENT_NOT_WRITABLE, 400, 409, 504). This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the purpose, then behaviors, requirements, errors, and related tools in scannable sentences. Dense but each clause carries information; only minor tightening is possible.

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

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

For a mutating, long-running, auth-sensitive tool with no output schema, the description compensates fully: it documents the return contract, timeout semantics, and every relevant error. Nothing needed 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 description coverage is 100%, so the schema already documents force, timeoutMs, followLink, and the agentId alias in detail; the description mostly corroborates rather than extends these. It adds the 409/force interplay, but that is already present in the schema, 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?

States a specific verb and resource ('Crawl a website URL') plus the blocking behavior ('wait...enqueues the job, then polls until completed or failed'), which distinguishes it from the sibling crawl-cancel and site-list tools. An agent knows exactly what this does 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?

Explicit preconditions are given ('requires a selected app via ethora-app-select or an explicit appId'), and failure paths route to named alternatives ('check with ethora-source-site-list, or stop it with ethora-source-site-crawl-cancel'). The force/re-crawl condition is also spelled out.

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 readOnly/idempotent/non-destructive, but the description adds genuinely new operational context: no auth required, effectively no error paths, and a security-relevant redaction guarantee ('booleans like hasAppJwt — values never echoed'). That is exactly the extra behavioral detail annotations cannot 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?

Extremely dense with zero filler, and the highest-value fact (what state is reported) is front-loaded. The trailing 'Auth/Errors/Related' fragments are terse to the point of being slightly clipped, but every clause carries information.

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

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

There is no output schema, so the description compensates by naming the returned fields, which is the right move. Combined with the auth and error disclosures, an agent has everything needed to call this zero-arg tool correctly and interpret the result.

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

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

The tool takes zero parameters, so there are no parameter semantics to document; per the baseline rule this is a 4. The description instead describes the response fields, which is useful but belongs to a different dimension.

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 ('Report the current Ethora MCP session state') and then enumerates exactly what is reported (API URL, auth mode, credential presence flags, appId/agentId, hosted/sessionId). It is immediately distinguishable from the large sibling set, which is dominated by create/update/list operations.

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

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

'Related: ethora-doctor for an active connectivity check' routes the agent to the alternative and implies the division of labor (passive snapshot vs. active probe). It does not spell out an explicit 'use this when...' trigger, but for a no-arg status tool the context is sufficiently clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on real behavioral context: no account data is touched, the list refreshes automatically via tools/list_changed, hosted-server sessions persist enabled groups across clients, auth is none, and the UNKNOWN_GROUP error is named. This is exactly the beyond-annotations detail that prevention-of-misuse requires.

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

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

Front-loaded with the session-only scope and default behavior before details, and nearly every sentence carries operational value. It is dense and slightly clause-heavy, but no sentence is filler; a small trim of the hosted-server nuance would tighten it without loss.

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 describing the catalogue return shape when `group` is omitted, plus auth, error token, and the full group key list. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100% and the enum already enumerates the groups, so the schema carries the load. The description still adds meaning the schema does not: the semantics of omitting `group` (returns a catalogue with per-group summary, tool count and enabled flag) and that `all` enables everything.

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 opening clause gives a precise verb and resource: it changes which tools the connection lists, and it is session-only. That scope is unmistakably different from every sibling (agents, apps, keys, etc.), so an agent can select it 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?

It states the default state ('only core tools are listed by default'), the condition for calling it, the alternative for reaching hidden tools ('described by `search` / `fetch`'), and the distinct behavior of calling it with no `group` argument. When-to-use, when-not, and the fallback path are all 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, the description discloses session-token storage, tool unlocking, API-key minting behavior, and error conditions. It does not contradict annotations, but it leaves the idempotency implication of createApiKey somewhat ambiguous despite idempotentHint=true.

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 action and side effect are front-loaded, followed by prerequisites and error semantics. Every sentence earns its place with no filler or repetition.

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

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

There is no output schema, so the description carries some burden for return-value behavior; it states the session token is stored and an API key may be returned once, but not the response shape. Prerequisites, errors, and side effects are otherwise sufficiently covered for a login 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 description coverage is 100%, so the schema already documents all five parameters. The description adds narrative context around email/password authentication and API-key minting, but does not materially enrich parameter meaning beyond the schema.

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

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

The description clearly states the action: authenticate an existing Ethora user with email and password. It also names the session-token side effect and the unlocked user-auth tool families, distinguishing it from sibling tools like ethora-user-register and ethora-api-key-create.

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

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

It gives explicit prerequisites: user-auth mode must be set via ethora-auth-mode-set first, and appJwt must be configured. It also documents error codes and the rate-limit retry guidance. It does not explicitly contrast with alternate authentication or API-key creation flows, but the 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?

Beyond the annotations' simple write hint, it discloses that a generated password is returned exactly once, a long-lived API key is minted by default for agent reconnection, and that auth uses a configured `appJwt`. It also enumerates concrete error codes for 401, 422, and 429, giving the agent actionable behavioral expectations.

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

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

The description is compact, front-loaded with the core action, and every sentence carries unique value—session binding, API key reconnection, auth prerequisites, error codes, and the sibling alternative. 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?

Despite having no output schema, the description covers the critical operational facts an agent needs: auth requirements, expected errors, default API key creation, and the one-time visibility of generated credentials. For a 7-parameter registration tool, this 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 description coverage is 100%, so the schema already documents every parameter. The description reinforces the generated-password-once behavior and the API key defaults, but adds limited meaning beyond the schema's own field descriptions. 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 opens with a specific verb and resource: 'Create a new Ethora user account by email + first/last name, then log in and bind the session.' It also differentiates itself from the sibling ethora-user-login and batch creation, making the tool's unique role 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?

It gives clear context: single-user registration with optional API key generation for agent reconnection, and names `ethora-user-batch-create` for bulk provisioning. It doesn't explicitly say 'use ethora-user-login for existing users,' but the registration-vs-bulk distinction is enough.

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

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

Annotations already declare readOnly/idempotent/non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that — no API call, placeholder output when no widget URL is configured, and the rule that inline cosmetic attributes override the app's saved look. This is useful, but a chunk of it (prerequisites) overlaps with usage guidance rather than pure behavior.

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

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

The core purpose is front-loaded and every sentence carries signal (prerequisites, auth, errors, related tools). It is dense and runs long, with some overlap between the usage and requirements sentences, so it falls short of a tight 5.

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 10-param generator with no output schema, the description covers prerequisites, auth, failure behavior, placeholder output, and related tools — enough for an agent to invoke it correctly. It never explicitly states the return shape (a snippet string), a minor gap 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 description coverage is 100%, so the baseline is 3 and the schema does the heavy lifting. The description still adds genuine meaning: it explains that cosmetic parameters write attributes that win over the saved appearance, and that `data-app-id` alone suffices, which is interaction semantics the schema does not convey.

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 opening sentence names a specific verb and artifact — generating the `<script>` tag that embeds the floating chat widget — and immediately scopes it as a pure generator with no API call. It explicitly distinguishes itself from siblings, noting `ethora-bot-widget-get` is the legacy per-app alternative.

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 preconditions (an activated agent, with the exact `create -> invite -> activate` chain that must run first), the failure mode if unmet (422, silent widget), and how to choose between parameters (`appId` preferred, `botId` only for old embeds). This is a full when/when-not/alternatives statement.

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 covered. The description adds two useful behavioral details: 'Auth: none required' and 'Errors: unknown id', which are not present in annotations. It also clarifies the return is 'full text'. This adds value beyond the structured metadata without contradicting it.

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. The first sentence front-loads the purpose and input source; the second adds auth and error details. Every clause earns its place. Ideal length for a simple fetch operation.

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

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

For a tool with one parameter, no output schema, and comprehensive annotations, the description covers the essential operational details: what it does, how to get the id, auth requirements, and error behavior. The return content ('full text') is implied. 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?

The schema has 100% description coverage for the single 'id' parameter ('Document id from a search result'), so the baseline is 3. The description adds concrete examples of id formats ('tool:ethora-app-create', 'doc:auth-map#app-jwt', 'doc:hosted-guide') and explicitly states the id comes from 'search', reinforcing the schema. This extra context justifies a score above baseline.

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

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

The description states a specific verb ('Fetch'), a specific resource ('the full text of a documentation section or tool reference entry'), and the source of the identifier ('by the id returned from search'). It clearly differentiates from sibling tools like 'search' by specifying it retrieves content by id, not listing/searching. Examples of id formats further clarify the 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 explicitly ties usage to the output of 'search' ('by the id returned from search'), giving clear context on when to call this tool. It doesn't explicitly state alternatives or when not to use it, but the sibling relationship with 'search' and the clear input contract make usage straightforward. It could have been more explicit about the search→fetch workflow, but the guidance is adequate.

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 idempotentHint=true, so the safe read-only nature is covered. The description adds useful behavioral context by noting 'Auth: none required' and implying the tool returns result IDs that can be passed to `fetch`. It does not disclose result limits or exact return shape, but it adds 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 front-loaded with the core action and scope, then gives concrete guidance, follow-up instruction, and auth info in a compact form. Every sentence earns its place and there is no redundant repetition of 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 one-parameter search tool with safety annotations already provided, the description is complete: it states what is searched, when to use it, the auth requirement, and the follow-up path to read full text via `fetch`. The absence of an output schema is mitigated by the clear 'result id' handoff instruction.

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 the query parameter with examples and empty-query behavior. The tool description adds usage-level guidance rather than parameter-level semantics, so a baseline 3 is appropriate; the schema is doing the heavy lifting.

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 has a specific verb and resource: 'Search the Ethora documentation and tool reference', then enumerates covered topics and even points to the sibling `fetch` tool for follow-up reading. This clearly distinguishes it from the many action-oriented sibling tools and the complementary `fetch` tool.

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

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

Explicitly tells the agent when to use this tool: for any 'how do I ...' question about Ethora before guessing. It also names the follow-up action (`fetch` with a result id), giving clear operational context beyond simple tool selection.

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