mcphost

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

With no annotations, the description carries the burden and does reasonably well: it discloses reuse semantics ('or reuse an open one for the same plan'), a named failure mode (billing_unavailable when no Stripe key), and a precondition. It stops short of describing auth requirements and what success returns beyond the URL.

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 dense sentences with zero filler, and the most decision-relevant facts (create/reuse, default plan, failure mode, prerequisite) are 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 two-optional-param tool with no output schema, the description covers purpose, default, idempotent reuse, error surface, and prerequisite. Only the auth-header nuance lives solely in the schema, which is acceptable.

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

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

Schema coverage is 100%, so both parameters are already documented, including the pro default and the tenant_key/auth-header precedence rule. The description's 'defaulting to the pro plan' merely restates the schema, adding no new meaning — 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 and resource — creating (or reusing) a Stripe Checkout URL — plus the scope (upgrade this tenant, default pro plan). This is clearly distinguishable from billing.plans and billing.status 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?

Explicitly tells the agent to call billing.plans first as a precondition check, which is real routing guidance. It does not, however, contrast this tool with billing.status or describe when checkout is *not* the right call.

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?

With no annotations, the description carries the burden of behavioral disclosure. It adds one meaningful behavior: anonymous and tenant callers see identical results. It does not state side effects, caching, or error behavior, though the read-oriented nature is implied by 'catalog.'

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

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

The description is a single, dense sentence that puts the primary purpose first and adds the anonymous-caller note without wasted words. It is appropriately sized for the simple scope.

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 catalog query with one optional parameter and no output schema, the description covers the key return content: prices, quotas, and Stripe configuration. It could go further by noting response shape or pagination, but none is likely needed at this complexity level.

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

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

The input schema already documents tenant_key at 100% coverage, so the baseline is 3. The description adds no additional parameter-level meaning beyond the schema, but it does reinforce that tenant identity likely does not alter the response.

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

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

The description clearly identifies the resource (plan catalog) and the exact content returned (price and quotas per plan, plus Stripe configuration status). It lacks an explicit verb like 'retrieve' or 'list,' but the intent is unambiguous and distinct from the billing checkout/status 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 implies this tool is for inspecting plan catalog data, and it provides a useful caller context: anonymous callers receive the same answer as tenants. However, it does not explicitly state when to choose this over billing.checkout or billing.status, nor does it mention any exclusions.

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 tells the caller what information is returned, which strongly implies a read-only status lookup. Since no annotations are provided, it does not explicitly state that no side effects occur or how authentication/tenant resolution is handled beyond the schema note on tenant_key.

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 one compact sentence with no filler. It front-loads the tenant scope and then lists the exact data points returned, making it easy to scan.

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

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

Given the single optional parameter and the lack of an output schema, the description adequately covers the main return values: plan, quota usage, and reset time. The missing explicit usage and side-effect caveats are minor for a simple status 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?

The input schema already fully documents the only parameter, tenant_key, including the precedence rule with the Authorization header. The description adds no parameter-level detail, so the baseline for high schema coverage 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 identifies the resource (this tenant's billing status) and the specific information returned: plan, quota usage, and reset time. It is clear enough to be distinguished from billing.plans, but it does not explicitly name or contrast any sibling tool.

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

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

The phrasing implies the tool should be used when the agent needs the current tenant's plan or quota consumption. However, it gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as billing.plans or host.usage.

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?

With no annotations, the description carries the behavioral burden. It discloses the key outcome: both parties become accepted contacts and see each other via host.agent.contacts(). It does not mention reversibility or permissions, but the core side effect is clearly stated.

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

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

A single, efficient sentence front-loads the action and immediately follows with the consequence. No redundant or filler words – every clause 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 two-parameter tool with no output schema or annotations, the description covers the action and its effect well. It could mention authentication prerequisites or error cases, but given the simplicity and the schema's completeness, 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 100%, so request_id and tenant_key are fully documented. The description adds no extra parameter-level detail beyond what the schema already provides, so a 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 uses a specific verb ('Accept'), names the resource ('pending contact request'), and clarifies the resulting state (both become accepted contacts). It is easily distinguished from siblings like host.agent.contact_deny and host.agent.contact_request, which serve different actions.

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 context is clear: use this when you want to accept a pending contact request addressed to you. It does not explicitly name alternatives like host.agent.contact_deny, but the intent is unambiguous, so no significant exclusion is needed.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses the key consequence—subsequent sends/requests from the denied requester get contact_pending for 7 days, then they may retry—which goes beyond a simple 'Deny' statement. It does not cover return behavior or auth specifics, but the main side effect is captured.

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 action is front-loaded and the consequence follows immediately. Every clause adds useful information for selecting and invoking 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?

For a simple tool with one required parameter and no output schema, the description covers the essential action and side effects. It could mention what happens in invalid/duplicate cases, but that is not critical to 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%, with both request_id and tenant_key documented. The description adds no parameter-level detail, but the schema handles that burden, so the 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?

The description uses a specific verb ('Deny') and a specific resource ('a pending contact request addressed to you'), clearly narrowing the operation's scope. It implicitly distinguishes this tool from contact_accept and contact_request even without naming them.

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

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

The description states the applicable context: only pending contact requests addressed to you. It does not explicitly name contact_accept as the alternative for approval, so the guidance is clear but lacks a direct exclusion/alternative 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?

With no annotations provided, the description carries the full behavioral burden and handles it well. It discloses that the tool creates or returns a pending request, enumerates the various status outcomes (not_needed, contact_refused, contact_pending, agent_not_found), reveals blocked-address behavior, and mentions the daily quota.

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

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

The description is compact and front-loaded with the core purpose, followed by a dense but efficient enumeration of expected outcomes and quota. Every sentence contributes useful information without padding.

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

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

The description is largely complete for a tool with no output schema and no annotations: it covers purpose, possible statuses, blocked behavior, and quota. It leaves the notion of 'contacts-mode address' somewhat unexplained, and no response format is described, but these are minor given the tool's scope.

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 does not add significant parameter-level meaning beyond what the schema already provides for address, note, or tenant_key; it focuses on outcomes rather than parameter details.

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

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

The description opens with a specific verb and resource: 'Request contact with a contacts-mode address; creates or returns the pending request.' It clearly identifies the action and outcome, and the contact-related context distinguishes it from siblings like contact_accept and contact_deny.

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 explicitly states when a request is not needed ('not_needed for an open address or one you already have an accepted contact with'). However, it does not explicitly name alternative tools, so it falls short of full when-to-use-versus-alternatives 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?

No annotations are provided, so the description carries full responsibility. It discloses the scope (accepted contacts and pending/decided requests) and the optional status filter, but does not mention whether the operation is read-only, any authentication requirements (beyond the tenant_key schema note), pagination, or rate limits. The 'List' verb implies read-only, but this is not explicitly stated.

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

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

The description is a single sentence that front-loads the main purpose (listing contacts/requests) and then explains the optional status filter. It is efficient with no wasted words, though it could be slightly more concise by dropping the redundant 'in either direction' phrase already implied by 'incoming/outgoing.'

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 (2 parameters, no output schema, no annotations), the description covers the essential behavior. However, it lacks any mention of the return format (e.g., array of objects) or pagination, and does not explain what 'decided' means in detail. An agent would know what tool to call but not what to expect back, leaving some ambiguity.

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

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

Schema description coverage is 100% for both parameters. The description adds minimal semantic value beyond the schema: it reiterates that status filters 'incoming/outgoing' (already in schema) and does not explain tenant_key beyond what the schema says. Since coverage is high, the baseline of 3 applies; the description does not enhance parameter understanding.

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 ('List') and resource ('accepted contacts' and 'pending/decided contact request in either direction'), and it distinguishes itself from siblings like contact_accept, contact_deny, and contact_request by focusing on enumeration rather than mutation. The scope and optional filtering are explicitly defined.

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

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

The description implies when to use it (listing contacts/requests) but does not explicitly mention alternatives or exclusions. It doesn't say 'use lookup for a single contact' or 'use contacts_import to add contacts.' While the context suggests it's the default list tool, explicit guidance on when not to use it is absent.

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

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

No annotations are provided, so the description carries the full burden. It discloses that per-address failures do not fail the whole call and are reported individually, which is key behavioral information. It also mentions the resolution is same as single request, setting expectations for semantics. This is good transparency but could be more explicit about other behaviors like rate limits.

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

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

The description is a single sentence and is reasonably concise. It front-loads the key batching capability and includes important exception handling. However, it could be broken into two sentences for readability, but it is not overly verbose.

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 output schema and no annotations, the description explains the calling behavior, error handling, and parameter context adequately. It mentions the 'same way as single request' which gives behavioral context. The main gap is that it doesn't describe what the success response looks like or provide examples of error entry format, but for the complexity level, it is fairly 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?

The schema coverage is 100%, so the schema already describes both parameters clearly ('addresses' format and tenant_key condition). The description adds minimal extra semantics beyond the schema: it explains the per-address error handling but not parameter-specific details. Since coverage is high, the baseline is 3, and the description adds some value but not significant new parameter insight.

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 request contacts with up to 50 addresses at once. It uses a specific verb ('request contact') and references the resource (addresses), and implies batching. It does not explicitly differentiate from sibling tools like host.agent.contact_request, but the batching aspect is clear from the description.

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

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

The description indicates this is for batch requests, implying use when you need to request multiple contacts. It does not explicitly state when not to use it or mention alternatives, but the batching context is clear. It also notes per-address failure handling, which helps set expectations. However, no direct comparison to single-request alternatives is given.

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?

With no annotations, the description carries the behavioral burden. It discloses an important security-relevant trait: unknown, disabled, and deleted addresses all return the identical agent_not_found error, preventing enumeration. It also specifies the public card fields returned, which is useful since there is no output schema.

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 densely informative sentences. The first front-loads the action and output shape, and the second adds the key error behavior. 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?

Even without an output schema, the description lists the returned card fields and the error semantics, so an agent knows what to expect. It could be more complete by explicitly stating that this is an exact-match lookup versus search, but it is otherwise sufficient 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 explains the @handle/namespace format for address and the Authorization header precedence for tenant_key. The description adds no parameter-specific meaning beyond what the schema already provides, 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 names a specific verb ("Resolve") and resource (another agent's namespace or @handle to its public card), and even enumerates the returned fields. It is clearly distinguishable from the broader host.agent.search sibling, though it does not explicitly contrast itself with that 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?

Usage is implied: pass an exact @handle or bare namespace to get the public card. There is no explicit when-to-use versus alternatives, no mention that this is not for fuzzy search, and no exclusions or preconditions beyond what the schema states.

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?

With no annotations, the description carries the full burden. It transparently discloses that messages remain stored and readable, are only hidden from the unread inbox unless urgent, and that mute is not a block or closed policy. It does not cover auth requirements or rate limits, but for a mute operation these are less critical. The description provides a clear behavioral model.

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

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

The description is a single dense sentence that front-loads the purpose and packs in the key behavioral details (storage, inbox exclusion, urgent bypass, not-a-block). It is concise with no filler, though it is long enough that an agent might need to parse it carefully. Still, every clause earns its place.

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

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

The description is complete for a mute tool: it explains the effect on inbox and threads, the urgent bypass, and the distinction from blocking. It does not mention return values, but there is no output schema and many tools omit that. It also doesn't explicitly address unmute, but that is a sibling tool. Overall, an agent has enough 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 schema already documents both parameters (address and tenant_key) sufficiently. The description does not add extra meaning beyond the schema; it refers to 'urgent: true' which is a property of messages, not parameters. Since the schema covers everything, 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 clearly states the verb 'mute' and the resource 'address', and explains the exact effect: messages are stored but excluded from the inbox, with an urgent bypass. It distinguishes from the sibling 'unmute' and clarifies it is not a block or closed policy, making the tool's 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 implies when to use it: when you want to silence an address while keeping history accessible. It explicitly notes the urgent bypass and states it is not a block, which differentiates it from host.msg.block. However, it does not explicitly say 'use this instead of block when...' or mention when to prefer unmute, leaving some inference to the agent.

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?

With no annotations, the description carries the full burden, and it delivers: omitted arguments leave fields unchanged, explicit null clears handle/description, taken/reserved handles fail with specific errors, handles are stored lower-case, tags and description have size caps, and contact_policy is enforced by the inbox PRD.

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

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

A single dense paragraph front-loads the core action, then packs constraints, semantics, and error behavior with no wasted words. Every clause 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?

Given five optional parameters rob and no output schema, the description covers invocation semantics, constraints, and failure modes well. The only minor gap is not describing what a successful response contains, though this is not essential 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?

The input schema already provides 100% parameter coverage with detailed descriptions, setting the baseline at 3. The description adds useful integration context like partial-update semantics and handle format, but does not substantially expand beyond what the schema already documents.

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: 'Claim or update this tenant's agent-directory card.' It names the exact fields handled and distinguishes this as the write/update sibling of read-only tools like host.agent.lookup, host.agent.search, and host.agent.whoami.

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 usage context is implied clearly: use this to create or modify an agent-directory profile. However, it never explicitly contrasts itself with the read-only agent tools or states when not to use it, so the routing to alternatives is left to inference.

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

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

With no annotations, the description carries the behavioral burden. It discloses exclusions (disabled tenants), ordering (handle with unclaimed last, then namespace), and pagination (cursor from previous response). It does not explicitly state read-only behavior, but the verb 'Find' implies it. This is solid disclosure beyond what the schema provides.

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

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

Three sentences, each earning its place: search criteria, exclusion rule, and ordering+pagination. No fluff, and the most critical information is front-loaded. Structure is optimal for a search 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?

The description covers search criteria, exclusions, ordering, and pagination—all key for a search operation. It omits description of the output structure, but there is no output schema, and the missing details (like authentication) are covered in the parameter schema. It is largely complete for effective usage, though a bit more on return format would push to 5.

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 provides thorough descriptions for all 5 parameters (100% coverage). The tool description adds minimal extra parameter meaning—it mentions ordering and pagination context, but these are also hinted in the schema's cursor description. The description does not materially enhance understanding of individual parameters beyond the schema, 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 states a specific verb (Find), a resource (agents), and its criteria (exact tag or substring of handle, display name, description). It's clear and distinct from sibling tools like host.agent.lookup, though it does not explicitly name any sibling to differentiate.

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

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

The description implies when to use the tool (searching agents by criteria) but provides no explicit guidance on alternatives or when not to use it. It doesn't mention host.agent.lookup or other related tools, so an agent must infer usage context from the name and description alone.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Remove a mute.' states only the action and gives no information about side effects, reversibility, permissions, idempotency, or what happens if the target is not currently muted. This is a significant transparency gap for a state-changing tool.

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

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

At three words, the description is extremely concise with no filler or repetition. The core purpose is front-loaded and every word contributes meaning.

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

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

The tool is relatively simple, has 100% schema coverage, and no output schema, so a long description is not required. Still, the description omits any guidance about success/failure behavior, authentication requirements, or relationship to host.agent.mute. It is minimally viable but has clear gaps.

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 explains both address and tenant_key. The description adds no parameter-level meaning beyond the action itself. Baseline 3 is appropriate because 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?

The description 'Remove a mute.' clearly identifies the action (remove) and the resource (a mute), which is enough to distinguish it from the sibling tool host.agent.mute. It is slightly terse and does not specify what kind of mute or target, but the input schema clarifies the address namespace. Overall clear but minimal.

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

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

The description implies usage by stating the action, and the tool name host.agent.unmute signals its counterpart host.agent.mute. However, it does not explicitly say when to use this tool instead of mute or any alternative, nor does it mention prerequisites or when not to use it.

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

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

With no annotations supplied, the description carries the transparency burden and does a good job: it explicitly declares the return scope and states an unusual negative guarantee ('Never a key hash, billing field, or call log'). It does not spell out idempotence or auth/rate-limit behavior, though 'Return' and the whoami semantics imply a safe read.

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 tightly packed sentences: the first leads with the verb, resource, and full field list; the second adds a valuable negative guarantee without restating any schema information. No wasted words.

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 naming the exact return fields and the optionality of the handle. It omits explicit error cases or detailed types for contact_policy/plan, but for a zero-required-param self-identity tool the provided context is nearly 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 100% for the single optional tenant_key parameter, which already documents the Bearer-header precedence. The description adds no parameter semantics, but none are needed; the baseline of 3 applies because the schema handles the parameter documentation.

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 ('Return') and identifies a distinct resource ('this tenant's own agent-directory address'), then enumerates the exact fields returned: namespace, handle, display name, contact_policy, plan. It does not explicitly contrast with the sibling host.whoami, but the 'agent-directory' qualifier and field list make the tool's purpose 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 phrase 'this tenant's own' implies when to use it as a self-identity lookup, and 'Never a key hash, billing field, or call log' provides a boundary. However, there is no explicit guidance about when to prefer it over sibling tools like host.whoami or host.agent.lookup/search, so routing between alternatives is left to inference.

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

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

With no annotations, the description carries the burden. It usefully discloses that this hits a 'real upstream' despite being a dry run, which flags real network side effects. However it says nothing about auth requirements, whether anything is persisted, or what the dry run returns.

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

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

A single compact sentence, front-loaded with the action and followed by the alternative. Zero filler; every clause earns its place.

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

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

The tool has nested object params and no output schema, so the description should explain the return of a dry run and the execution/auth model. Instead it covers only the action line and an alternative pointer, leaving the agent under-informed for a network-touching test 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% and the schema richly documents all three parameters, including the tenant_key auth precedence rule. The description adds no parameter-level meaning beyond what the schema already provides, so this is 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 (dry-run) and resource (an unpublished http spec) plus the target (its real upstream). It carves out scope against siblings by deferring 'the other cases' to host.quickstart, so an agent can orient quickly. It stops short of naming exactly which sibling cases are excluded.

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 implies usage via 'unpublished http spec' and routes non-matching cases to host.quickstart, which is useful. But 'the other cases' is not spelled out, so the agent must infer whether an already-published spec, a non-http spec, or a plain tool test belongs elsewhere.

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?

No annotations are provided, so the description carries the full burden. It does disclose a real behavioral constraint — only *public* tools are returned, plus the two fields in the response (descriptor, args_schema) — but it says nothing about auth requirements, behavior when the name is unknown or non-public, or error/empty results.

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

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

A single front-loaded sentence with zero filler; the verb, resource, and lookup key are all in the first clause.

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

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

For a simple two-parameter read tool with a fully documented schema, the description covers the essentials and even compensates for the absent output schema by naming the returned fields. Only failure/not-found behavior and the public-only scope's implications are left unstated.

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

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

Schema description coverage is 100%, and the description's restatement of the full_name format (<namespace>.<name>) merely duplicates the schema. The auth nuance for tenant_key lives in the schema, not the description, so no added meaning is contributed. 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 verb and resource — 'Return one public tool's descriptor and args_schema by its full name' — so an agent knows exactly what it retrieves and in what key. It contrasts implicitly with the sibling host.catalog.search by emphasizing 'one ... by its full name', but it never names that sibling, so the differentiation is left to inference.

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?

Usage is only implied: 'by its full name' signals this is the lookup you use when you already know the exact <namespace>.<name>, versus browsing via host.catalog.search. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the search spans every tenant and only returns public tools, but says nothing about read-only nature, auth behavior, or pagination limits beyond what the schema states.

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

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

A single short sentence with the scope and matching mechanism front-loaded. Every phrase (public, every tenant, name/description) earns its place with zero 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 filtered search with no annotations and no output schema, the description covers scope and matching but not return shape, ordering, or how limit interacts with results. Adequate but with clear gaps for an agent needing to interpret results 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 three parameters are already documented in the schema, establishing a baseline of 3. The description adds only that the substring matches on name/description, a marginal clarification over the schema's 'Substring to match'.

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 (Search) and resource (public tools) plus the matching mechanism (name/description substring) and cross-tenant scope. It does not differentiate from the sibling host.catalog.get, which an agent might also select, so it falls 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?

Usage is implied by the name and the cross-tenant scope, but there is no explicit when-to-use, when-not, or comparison to alternatives such as host.catalog.get. The agent must infer the selection criteria from the tool name alone.

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?

No annotations are provided, so the description carries the full burden. It explicitly labels the operation 'Read-only' and defines the returned information as additions, deprecations, and removals. It does not discuss auth or edge cases, but for a safe list-style changelog the core behavior is disclosed.

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?

One compact sentence with a follow-up 'Read-only.' that earns its place. The main action, scope, and output categories are front-loaded with no wasted words.

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 changelog tool with two optional parameters, the description plus rich parameter schema is sufficient for correct invocation. There is no output schema, but the description names the three change categories, so callers know what to expect; only version-matching mechanics are left unspecified.

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%: both optional parameters are well documented, including the 'since' version format and tenant_key auth semantics. The description only restates the optional-version idea, so the schema does the heavy lifting and 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?

States a specific verb ('List') and a precisely bounded resource ('what changed in the host.*/billing.* tool surface'), including output categories (additions, deprecations, removals) and an optional version filter. No sibling tool covers this same meta-function, so no further differentiation is needed.

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 phrase 'List what changed ... since an optional version' gives clear retrieval context: use this when you need the change history of the host.*/billing.* tool surface. It does not name when-not-to-use or alternatives, but no sibling tool is a plausible 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?

With no annotations, the description carries the full burden and it does disclose key behaviors: ownership requirement, the effect on subsequent post calls, and the fact that read operations remain functional. It could add idempotency or error details, but it goes well beyond a bare 'close channel' statement.

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 tightly packed sentences: the first states the action and restriction, the second gives the observable behavioral outcome. No filler, 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 simple two-parameter tool with no annotations and no output schema, the description covers purpose, authorization, and post-condition behavior. It does not describe return values or what happens on repeated close attempts, but the essential information for invoking 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?

Schema description coverage is 100%, so the schema already documents both channel_id and tenant_key adequately. The tool description adds no parameter-level meaning beyond what the schema provides, so the 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?

The description uses a specific verb and resource ('close a group channel') and immediately identifies the owner-only restriction. It is clearly distinct from sibling operations like open, freeze, and unfreeze, and the stated post/read behavior further disambiguates it.

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 tool is owner-only, which is a clear access condition, and explains the practical consequence: posting will fail with channel_closed while reading continues to work. It does not explicitly name alternatives like host.channel.open or freeze, but the usage context is clear enough.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the authorization prerequisite (owner-only), the state change (freeze), and precise consequences on related calls: host.channel.post returns channel_frozen while host.channel.read keeps working. This is strong, concrete 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 two tight sentences: the first front-loads the operation and owner restriction, the second packs the key side effects into a compact, semicolon-joined clause. 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 simple 2-parameter mutation with no output schema, the description gives enough selection and side-effect context for a correct call. It omits the reversal path (host.channel.unfreeze) and response/error details, but neither is required for basic invocation.

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

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

Schema description coverage is 100%, so the schema already documents channel_id and tenant_key. The description adds no further param-specific semantics beyond referring to 'a group channel', which is consistent with the schema but not additive.

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 ('freeze a group channel') and sharpens scope with 'Owner-only'. It differentiates itself from siblings by specifying the effect on host.channel.post and host.channel.read, making the tool's 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 clearly states when the tool is appropriate: owner-only action on a group channel, with the consequence that posts are blocked but reads still work. It does not explicitly name alternatives like host.channel.unfreeze or host.channel.close, but the context is clear enough for an agent to decide 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly mentions idempotency ('return the existing one', 'idempotently'), the side effect of granting post/read access to current members, and the quota_exceeded error. This goes well beyond the schema and gives the agent a clear picture of what happens on call.

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-loaded with the primary purpose and then detailing the alternative mode and a key error condition. There is no fluff; every clause contributes to the agent's understanding. The structure is logical and efficient, making it easy to parse quickly.

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 main behaviors: creation, idempotent return, group-specific opening, and quota limit. It implies the return value ('return the existing one') but does not explicitly state the output format or what happens if both name and group are provided. Given there is no output schema, a more explicit statement about the return value would improve completeness, but the core usage is sufficiently covered.

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 each parameter already has a description. The tool description adds value by clarifying that name and group are mutually exclusive ('with group instead of name'), and that group must be a group you own. It also reiterates the auth nuance for tenant_key. This enriches the schema without repeating it verbatim, though it does not add syntax-level details beyond what the schema provides.

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

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

The description clearly states the tool's core function: create or return a named channel, or open the one channel for a group you own. It uses specific verbs and resources, and distinguishes itself from sibling tools like host.channel.close or host.channel.freeze by focusing on creation/opening. The two modes (name vs group) are explicitly described, leaving no ambiguity about 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 gives clear guidance on when to use this tool: when you need to create or open a channel, either by name or by group. It implies alternatives by naming other actions like post/read, but does not explicitly state when NOT to use it (e.g., for closing or freezing). However, the context is clear enough for an agent to infer the appropriate use case. It also mentions the quota_exceeded failure condition, adding practical 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?

With no annotations, the description carries the full burden and discloses the read cursor advancement and the specific channel_not_found error for non-members. However, it omits other behaviors like rate limits, auth requirements, or success response format.

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

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

Two concise sentences: the first states the core purpose and side effect, the second gives error behavior. Every word earns its place, and key 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?

Covers the main action, side effect, and an important error case. While it doesn't describe the success return (no output schema) or broader context like rate limits, it is adequate for a post operation with complete schema 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?

Schema coverage is 100%, and the description only repeats the channel name-or-id semantics already in the schema. It adds no new parameter details beyond what the schema provides, 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 states a specific action (post) on a specific resource (channel by name or channel_id) and adds a distinctive side effect (advances read cursor). This clearly differentiates it from generic send tools like host.msg.send.

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?

No explicit mention of when to use this tool over siblings such as host.msg.send or host.channel.read. The member/non-member error behavior provides context but does not guide alternative 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?

No annotations are provided, so the description fully carries the behavioral disclosure burden. It discloses a key side effect (ack: true stores next_cursor as your read position), an error condition (non-member gets channel_not_found), and the ordering semantics. This goes beyond the schema's parameter descriptions and helps an agent anticipate consequences and failure modes.

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

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

The description is compact, with the core purpose front-loaded and only a few additional sentences for behavior. It avoids fluff and each sentence adds value (defaults, ack side effect, error case). It is slightly dense but appropriately sized for the tool's 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?

With no output schema and no annotations, the description should clarify the return value and error cases more thoroughly. It mentions next_cursor implicitly but never states the response shape (e.g., posts and next_cursor). It also omits rate limits or pagination nuances beyond the schema's limit parameter. It is adequate but has clear gaps.

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 does not add much beyond the schema: cursor's default behavior is mirrored in the schema ('omit to resume from your own stored cursor'), and ack's meaning is already stated. It restates information rather than providing new semantics, so it does not exceed 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 states a specific action (read), a concrete resource (a group channel's posts), and a precise ordering (seq order, since a cursor). It clearly differentiates from sibling tools like host.channel.open (which creates/opens a channel) and host.msg.inbox (which reads a user's inbox), so an agent can select it appropriately.

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 explains the default cursor behavior (your own last read position or 0 for first read) and the effect of ack: true, which is useful operational guidance. However, it does not explicitly state when to choose this tool over alternatives (e.g., host.msg.inbox for per-user message reads) or when not to use it. The context is present but exclusions and alternatives are not 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?

With no annotations, the description carries the full behavioral burden. It discloses an authorization requirement (owner-only) and a concrete post-condition for the channel ('next post succeeds with the next seq'). It does not cover error cases or idempotency, but the core mutation behavior is clearly and usefully described.

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

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

The description is a single compact sentence with no filler. The critical owner-only constraint is front-loaded, followed by the operation and its effect, making the tool easy to scan and understand.

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 inverse operation with only two parameters and full schema coverage, the description supplies the essential context: purpose, authorization, and post-condition. It does not describe return values or error behavior, but those are not blocking for this tool and no output schema exists to require richer explanation.

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 both parameters are already well documented: channel_id is described as the group channel's id, and tenant_key explains its exact auth fallback condition. The description adds no parameter-level detail, but the schema fully compensates, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('unfreeze') and resource ('channel'), explicitly identifies itself as the inverse of host.channel.freeze, and gives the observable result ('the next post succeeds with the next seq'). This clearly differentiates it from sibling channel tools such as freeze, open, close, post, and read.

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 marks the operation as owner-only, establishing a clear authorization precondition for use. It also names the exact operation it reverses, which implies the appropriate context; it does not spell out when-not-to-use or list alternatives, but for a straightforward inverse action this 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?

No annotations are provided, so the description must carry the burden. It does disclose that the operation is a soft-delete and that deleted documents remain visible via host.docs.list with 'since' and deleted: true, which is valuable behavioral context. However, it does not mention reversibility, permissions required, or side effects beyond visibility, which are important for a mutation operation with no 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 a single, practically worded sentence that front-loads the action and key conditions. It conveys the most important behavioral nuance (soft-delete, still visible) 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?

The tool has 3 parameters, all optional, and no output schema. The description covers the core behavior and how to find deleted docs, but given no annotations, it could have elaborated on permissions or reversibility. However, the schema is clear and the description is adequate for a simple soft-delete operation; it is not highly complex, so a 3 is reasonable.

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

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

Schema description coverage is 100%, so the schema already explains each parameter (id, name, tenant_key). The description adds minimal extra meaning by explaining the id/name relationship (use one or the other) and tenant_key's role, but it mostly restates what the schema says. Since coverage is high, a baseline of 3 is appropriate; the description doesn't need to add much more.

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 ('soft-delete') and the resource ('document'), and specifies it can be done by id or name. It distinguishes from siblings like host.docs.purge (hard delete) and host.docs.put (create/update) by indicating soft-delete behavior. However, it does not explicitly differentiate from all potential document-related tools, but the core purpose is 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 implies when to use this tool (when you want to soft-delete a document) and hints at the alternative of using host.docs.list with 'since' to see deleted docs, but it does not explicitly name alternatives like host.docs.purge for permanent deletion or host.docs.put for creating/updating. It provides some context but lacks explicit when-not-to-use or alternative tool names.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that version defaults to current, that text:true returns extracted plain text produced at put time, and that tenant_key is only required when no Authorization header is present. This is meaningful behavioral context beyond the schema. It doesn't mention error cases or whether the read is safe, but the read-only nature is evident from 'Read'.

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

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

The description is a single sentence that front-loads the core action and resource, then packs the two most important behavioral nuances (version default and text extraction) into a compact clause. Every word earns its place; 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?

For a read tool with five optional parameters and no output schema, the description covers the key decision points: id vs name, version default, text flag, and tenant_key requirement. It doesn't describe the return shape, but with no output schema that would be useful; however, the tool is simple enough that an agent can infer the return from the parameters. The missing return-format note is a minor gap.

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 value by clarifying the id/name mutual exclusivity ('use name instead if you don't have it') and the tenant_key/Authorization header precedence, but these are also partially in the schema. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds only modest extra 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 states a specific verb ('Read') and resource ('a document by id or name'), and immediately distinguishes itself from sibling tools like host.docs.list, host.docs.delete, and host.docs.put. It also clarifies the default version behavior and the optional text extraction, making the tool's 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 implies when to use this tool: when you have a document id or name and want to read it. It doesn't explicitly name alternatives or exclusions, but the sibling context (host.docs.list for listing, host.docs.put for writing) makes the usage context reasonably clear. A brief 'use host.docs.list to enumerate documents' would have made it 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a significant side effect: changing config re-indexes every document from scratch in the background. It also explains the conditional requirements for the 'openai-compatible' provider and the role of the secret as a bearer. Missing details like reversibility and return value are minor given the absence of 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 a single, well-structured sentence with a colon-delimited list of provider options and a side-effect note. It is front-loaded with the primary purpose, uses no filler, and every clause contributes to understanding the tool's behavior.

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 conditional parameters and background reindex side effect, the description covers the essential operational context: provider choices, required fields for non-default providers, and the automatic reindex trigger. It omits the return value (no output schema exists) and doesn't mention prerequisites like setting up the tenant secret, but these are secondary to the core configuration task.

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% coverage, so the schema already documents all parameters. The description adds clarifying context by tying provider 'openai-compatible' to required endpoint, model, and secret, and noting dims is 'for documentation purposes'. However, it mostly restates schema text and does not add deeper semantics such as value formats or examples, so a baseline score of 3 is appropriate.

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

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

The description states a clear verb ('Configure') and a specific resource ('this tenant's search index provider'), and it distinguishes the tool from siblings by focusing on provider selection rather than indexing operations like host.docs.reindex or host.docs.put. It also explicitly introduces the two provider options and the default, making the tool's role 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 implies when to use this tool by explaining that changing config triggers reindexing, which clarifies the relationship with manual reindex tools. However, it does not explicitly mention alternative tools or conditions for choosing them, leaving some inference to the agent. The context around provider options and the automatic reindex side effect provides practical 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?

With no annotations provided, the description carries the behavioral burden. It discloses key behavior beyond the schema: 'including deleted ones (deleted: true)' and that '0' means everything. It also scopes the operation to the tenant. It does not mention pagination, ordering, or read-only status, but 'List' and the schema's cursor hint cover the most important remaining aspects.

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 tightly written sentences. The core purpose is front-loaded, and the conditional behavior is expressed clearly in one clause. No filler or repetition of the schema.

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 list tool with five optional parameters and no output schema, the description is largely sufficient: it defines the two calling patterns and the key behavioral nuance. The only real omission is a description of the return structure, but the schema's reference to 'next_cursor' indirectly implies the shape, so the gap is minor.

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 the 'since' semantics more fully than the schema: it introduces the watermark source (host.docs.status), clarifies that 0 means everything, and surfaces the deleted-document behavior. This goes beyond what the parameter descriptions already state.

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 opens with a specific verb and resource: 'List documents in this tenant's document store.' It then distinguishes the tool's two operating modes (live snapshot vs. changed-since), which clearly separates it from the related docs.* siblings (get/put/delete/purge/status) without needing 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?

The description gives clear context for when to use each mode: omit 'since' for a live snapshot, provide 'since' (a watermark from host.docs.status) to get changes including deleted documents. It references the source of the watermark explicitly. It doesn't name alternative tools or state when-not-to-use, but the two-mode guidance is strong enough for correct usage.

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?

With no annotations, the description carries the burden of behavioral disclosure. It goes beyond the basic action by exposing an important postcondition: after purging, reading a dropped version returns not found. It does not mention irreversibility, auth requirements, or rate limits, but the core destructive side effect is clearly conveyed.

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

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

The description is a single sentence with no filler, and the main action and condition are front-loaded. The postcondition is expressed compactly using the {version: ...} response notation.

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 version-pruning tool with no annotations and no output schema, the description adequately conveys the action, retention condition, and consequence of reading dropped versions. It could be more complete by noting what the purge call itself returns or explicitly warning that the operation is irreversible, but the essential behavior is clear enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description references older_than_versions but adds no new parameter-level detail such as accepted value ranges, defaults, or edge-case behavior.

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 ('Drop') and resource ('stored versions of a document') with a retention condition based on older_than_versions. It is clearly distinct from sibling docs.delete, which removes a whole document, and from docs.get/list/put/status.

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

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

The description implies when to use this tool: when you want to prune old versions of a document while keeping a certain number of recent ones. However, it does not explicitly contrast it with docs.delete or describe scenarios where this tool should not be used.

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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses versioning on name reuse, mime detection rules and allowed mimes, the size limit with its configurable default, and the no-op behavior for identical content. These are exactly the behavioral traits an agent needs to predict side effects.

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

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

Three sentences, front-loaded with the core action, then the key constraints. Every sentence adds necessary information: versioning, mime handling, size limit, and idempotency behavior. No filler or repetition of schema details.

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

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

For a write tool with six parameters and no output schema, the description covers the essential behavior: what it writes, versioning, mime constraints, size limit, and no-op semantics. It does not describe the success return value or error cases, but the absence of an output schema lowers the burden. A brief note on what a successful put returns would have made it 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 100%, so the baseline is 3. The description adds value beyond the schema by explaining mime detection from name/content, the size limit applying to content and content_base64, and the no-op condition. It does not add much about metadata or tenant_key, but the schema already covers those adequately.

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 ('Write') and resource ('a document in this tenant's document store'), and immediately clarifies the versioning behavior for already-used names. This distinguishes it from sibling doc tools (get, list, delete, purge, status) without needing to name them.

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

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

The description gives clear context for when to use the tool: to write or create a new version of a document. It does not explicitly mention alternatives or exclusions, but the write-versus-read/delete distinction is implicit and obvious from the sibling list. A direct pointer to host.docs.get for reading would have made it 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?

With no annotations, the description carries the behavioral burden and does so well: it discloses that reindexing is forced, that it may include re-embedding only when a provider is configured, and that it takes effect on the indexer's next tick. It stops short of noting side effects such as temporary search staleness or cost, 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?

One compact sentence delivers the action, the conditional embedding caveat, both invocation modes, and the timing. No filler or redundant structured data.

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

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

For a two-parameter tool with complete schema coverage and no output schema, the description covers operation, scope, and timing. It does not describe return values or effects on current search availability, but these are not essential to invoking 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?

Input schema coverage is 100%, so the schema already documents both parameters. The description mainly restates the document_id semantics; the added 're-chunk/re-embed' and 'next tick' context is operation-level rather than parameter-level. This meets the baseline but adds little parameter-specific value.

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

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

The description names a specific action (force re-chunk/re-embed) and a clear resource (tenant search index), and distinguishes the two invocation modes: one document via document_id or every document. This is enough to separate it from sibling docs tools like put or status.

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 tool's purpose is clear enough to know when to call it, but there is no explicit guidance about when to prefer it over alternatives such as host.docs.put or host.docs.status, and no stated exclusions. The usage is implied rather than stated.

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?

With no annotations present, the description carries the full burden and does so well: it discloses the mode-dependent ranking behavior (BM25 default, cosine in embeddings mode), the fallback to lexical when provider calls fail, the exact return shape, and that an index block reports mode and index staleness. This tells the agent what will happen at invocation time beyond what any schema field could 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?

Three sentences, each earning its place: the first front-loads the core purpose, the second explains behavioral nuances, the third documents the return format (which substitutes for a missing output schema). 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?

Given the moderate complexity (nested filter object, no annotations, no output schema), the description covers the essential gaps: it specifies the return structure since there is no output schema and explains fallback/staleness behavior. Minor omissions—explicit result ordering by score, pagination semantics beyond k, and error behavior—keep it from a 5.

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 of 3 applies even without parameter info in the description. The description adds no parameter-specific meaning beyond the schema; the only connection is that embeddings mode is set via host.docs.index_config, which orients behavior rather than any parameter. The schema adequately handles the parameter 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?

Opens with a specific verb-resource pair ('Ranked passage search over this tenant's document store') and the qualifier 'passage' differentiates it from sibling retrievers like host.docs.get, host.docs.list, and host.catalog.search. The ranking detail (BM25 vs cosine) further pins down what this tool uniquely 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 gives clear domain context (tenant document store) and hints that the ranking mode is configured via host.docs.index_config, which is a useful pointer to an interacting sibling. However, it never explicitly says when to choose this over alternatives, nor does it state exclusions such as 'use host.docs.get for a single document' or 'use host.docs.list for metadata.' Selection guidance is implied, not stated.

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?

With no annotations, the description carries the burden of behavioral disclosure. It enumerates the return fields but does not explicitly state that the operation is read-only or has no side effects. The name 'status' and the nature of the fields strongly imply a safe read, but this is not stated. It also does not mention any authentication or error conditions.

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

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

The description is a single, dense sentence that front-loads the primary content (counters, quotas) and then details the index block. It is efficient and avoids fluff, though it could be slightly better structured with a leading verb.

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 lists all returned fields explicitly, which is essential since there is no output schema. Field names are self-explanatory. It does not cover error handling or prerequisites, but for a status read these are less critical. Overall, it provides enough context for an agent to understand what the tool returns.

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

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

The single optional parameter tenant_key is fully documented in the schema (100% coverage), including when it is required. The description does not add any parameter-specific guidance, but the schema already covers it, so the baseline of 3 applies.

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

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

The description clearly states the tool returns document store counters, quotas, and index status fields. The verb is implicit ('status' implies retrieval), but the content is specific and distinct from siblings like host.docs.list or host.docs.get, which operate on individual documents.

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?

No guidance is given on when to use this tool versus alternatives. It does not mention that it's a read-only status check, nor does it contrast with host.docs.index_config or host.docs.list. An agent must infer from the name that it's a status endpoint.

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?

With no annotations present, the description fully discloses the behavior: the secret is returned once, never shown again, never appears in host.secret_list, and old secrets stop verifying with no overlap window. It also specifies the signing algorithm and claim constraints. The agent knows exactly what happens.

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

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

The description is a single, information-dense sentence that front-loads the purpose and immediately follows with the critical behavioral caveats. Every clause adds value and no unnecessary words are present.

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's purpose, the cryptographic details, the return behavior, the persistence (or lack thereof) of the secret, and the security implications (no overlap). Combined with the schema's parameter documentation, 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%, and the single parameter tenant_key is already well-documented in the schema, including the condition for when it's needed. The description adds no additional parameter semantics, 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 names a specific verb ('Generate and store'), a specific resource ('per-tenant secret for signing end_user_assertion'), and details the token format (HS256 compact JWS) and claims (sub/iat/exp). This clearly distinguishes it from generic secret tools like host.secret_set or host.key_rotate.

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

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

The description implies usage context by explaining the secret's uniqueness and the immediate invalidation of prior secrets, which suggests this is the tool to rotate the assertion secret. It does not explicitly name alternatives or say 'when not to use', but the context is clear enough for an agent to decide.

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?

With no annotations, the description carries the behavioral burden and largely meets it: it discloses the identity source (OAuth bearer sub/iss or verified end_user_assertion), the output shape, and the null behavior. It stops short of explicitly stating there are no side effects or rate-limit/auth failure behaviors, but the passive 'carries' wording strongly implies a read-only query.

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

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

A single dense sentence front-loads the core result ('the end user this call carries') and then packs the source, fields, and null case without wasted words.

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 introspection tool with no output schema, the description is complete: it explains what the agent will get back, the exact fields, the null case, and the one optional parameter is fully documented in 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 documents tenant_key, including the bearer-header precedence. The tool description itself adds no parameter semantics beyond the schema, so the 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?

The description identifies the tool's subject precisely: the verified end-user identity carried on the current call, with the exact fields it contains and a null fallback. It does not use an explicit action verb like 'return' or 'get,' but 'whoami' plus the description 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?

The description implies when to use this tool: when you need the end-user identity attached to the current call, and it notes the no-identity case. It does not explicitly distinguish this from sibling tools like host.whoami or host.agent.whoami, nor give exclusion criteria.

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?

With no annotations provided, the description carries the full burden and covers key behaviors: background job execution, deduplication (returns same run_id if already running), 24-hour download validity, and the result structure. It does not discuss side effects like disk cleanup, but readability is high and important operational details are disclosed.

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: the main purpose comes first, followed by operational details (background job, polling, deduplication, URL validity). It is longer than a single sentence but every sentence delivers necessary information 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?

The description covers the tool's behavior, parameters, and how to retrieve results (poll runs.get). Since there is no output schema, it appropriately explains the run result's download_url and validity. It lacks details on manifest.json structure or error handling, but for a background export tool it is largely 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?

The input schema already provides 100% coverage for both parameters. The description adds value by explaining the default for tools ('every tool when omitted') and the condition for tenant_key (only needed when no auth header, header wins). This goes beyond the schema's descriptions, so 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 clearly identifies the action (build a downloadable .tar.gz), the resource (everything this tenant owns), and enumerates contents (tool sources, state, secret names, history, usage, manifest.json). It distinguishes itself from siblings like host.tool_publish and host.runs.get by stating the export scope and re-publishability.

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 on when to use (when a full tenant export is needed) and how it behaves (background job, polling via host.runs.get). However, it does not explicitly state when not to use it or mention alternatives, but for a unique export tool this is sufficient 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?

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It discloses the ownership precondition but says nothing about idempotency, duplicate membership handling, reversibility (a sibling host.group.remove exists), or failure modes.

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

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

A single tight sentence with the key constraint front-loaded and no wasted words.

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 annotations and no output schema, the one-liner plus strong parameter docs cover the basics, but behavioral details an agent would want (idempotency, duplicate handling, permissions) are absent.

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 name, namespace, and the tenant_key auth fallback. The description's '(by namespace)' adds clarifying intent but no syntax or meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb (add) and resource (tenant to group), plus clarifies the tenant is identified by namespace. It is distinguishable from siblings like host.group.create and host.group.remove, though it never names an alternative explicitly.

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 conveys a prerequisite ('a group this tenant owns'), which implies when the call is valid, but there is no explicit guidance on when to use this versus host.group.create/remove or how membership interacts with those. Usage must be inferred.

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?

With no annotations, the description carries the full behavioral burden for a mutation, yet it says nothing about name uniqueness/idempotency, what happens when a duplicate name is submitted, required auth, or what is returned. Only the tenant-ownership scope is disclosed, leaving the error and permission surface undocumented.

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

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

A single front-loaded sentence with zero filler; the creation act and its downstream purpose are both expressed without redundant restatement of the name or 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 2-parameter mutation with no annotations and no output schema, the description covers the intent but omits what the caller receives back -- notably the group identifier needed to reference the group in host.tool_share. It is minimally adequate rather than 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 both `name` and `tenant_key` are already documented with their usage conditions. The description adds no parameter-level detail beyond that, so the 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?

The description gives a specific verb+resource ("Create a named group") and scopes it to the calling tenant, which is genuinely useful. It does not, however, disambiguate itself from the close sibling host.group.add, which an agent could easily confuse with creation.

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

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

It states a concrete reason to call it -- producing a group consumable by host.tool_share(visibility: "group") -- which gives the agent a clear trigger. It stops short of naming when not to use it or pointing at host.group.list/remove as the lifecycle 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?

With no annotations, the description carries the disclosure burden; it does add that members are returned alongside groups and that results are tenant-scoped, which is useful. It does not state read-only status explicitly, nor anything about ordering, pagination, or what happens when the tenant owns no groups.

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

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

A single front-loaded sentence with no filler; the scope and return payload are both stated up front. It is arguably terse for a tool whose behavior beyond the schema is undocumented.

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 list with one optional, fully documented parameter and no output schema, this covers what an agent needs to call it. The only shortfall is the absence of any usage framing relative to the many sibling group and host tools.

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

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

Schema description coverage is 100%, so the schema already fully documents tenant_key including the 'header wins' precedence rule. The description adds no additional meaning about the parameter, 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?

States a specific verb (List) and resource (groups) scoped to 'this tenant', plus the returned payload (groups and their members). It is distinguishable by verb from siblings host.group.add/create/remove, though it never names them explicitly.

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?

No when-to-use, when-not-to-use, or alternative guidance is provided. The read-only nature is only implied by 'List', and nothing tells the agent how this differs in practice from host.whoami or the group mutation siblings.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a destructive mutation but does not state whether removal is reversible, what happens to the removed member, what permissions are required, or any side effects; only the ownership precondition is hinted at.

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

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

A single compact sentence with the scope qualifier front-loaded and no wasted words. It is appropriately sized, though its brevity contributes to the behavioral gaps noted elsewhere.

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 tool with no annotations and no output schema, the description is too thin: it omits reversibility, permission requirements, error conditions (e.g., tenant not a member), and any confirmation semantics an agent would need before calling 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%, so the schema already documents all three parameters including the tenant_key authorization nuance. The description adds only a light restatement ('by namespace'), which does not exceed the schema 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 a specific verb ('Remove') and resource ('a tenant ... from a group'), with the qualifier 'this tenant owns' narrowing scope. An agent can distinguish it from host.group.add and host.group.create from the verb alone, though no sibling is named explicitly.

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 phrase 'a group this tenant owns' implies a precondition (ownership) that gates legitimate use, but there is no explicit when-to-use guidance and no alternative sibling (e.g., host.group.list or host.group.add) is referenced for the inverse 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?

With no annotations provided, the description carries the full burden and does so well: it discloses the destructive/irreversible effect (old key fails as unauthenticated immediately), and the one-time-only visibility of the returned key. These are exactly the behavioral traits an agent must know before calling a credential-mutating tool.

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

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

Two tight sentences with no filler; the rotation action and its destructive consequence are front-loaded, and the follow-up usage instruction comes second where it belongs. Every clause 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?

Given a single optional parameter, no annotations and no output schema, the description covers the return value ('returns the new key exactly once') and the auth contract, which is most of what an agent needs. It omits any authorization prerequisite for calling the rotation itself (e.g. what credential is required to rotate), a minor but real gap for a security-sensitive operation.

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

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

Schema coverage is 100% and the single tenant_key parameter is already fully documented, including the Authorization-header precedence rule. The description only adds that the new key works 'as tenant_key or Authorization', which is a marginal restatement rather than new syntactic or format meaning, so the 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 verb+resource (rotate/issue a new tenant key) and its immediate effect (invalidate the current one), so an agent can tell at a glance that this is a credential-rotation operation. No sibling tool in the list performs key rotation, so no disambiguation is needed.

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 post-invocation guidance ('use it as tenant_key or Authorization for every call after this one') and states the consequence of not doing so. It never names an explicit when-to-rotate condition or when-not (e.g. key compromise vs. routine rotation), so it stops short of a full when/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?

No annotations are provided, so the description carries the full burden. It discloses meaningful behavior: the effect on unread_only inbox queries and that receipts are per-recipient and invisible to the sender. It does not state idempotency, whether marking nonexistent IDs errors, or auth beyond what the schema conveys.

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 clauses, front-loaded with the core action, then the behavioral consequence, then the scoping rule. Every sentence earns its place 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 two-parameter mutation tool with no annotations and no output schema, the description covers the essential semantics (effect and scoping) but omits return behavior, error cases, and idempotency. Adequate but with clear gaps given the lack of structured behavioral data.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds only the per-recipient framing ('for you'), which is consistent with but not richer than the schema's 'mark read for you.' 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?

Clear verb+resource: 'Mark messages as read for you.' It states the effect on the inbox (unread_only reads stop returning them) and the per-recipient scoping. It doesn't explicitly distinguish from siblings like host.msg.inbox or host.msg.thread, but the read-receipt semantics make its domain 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?

Usage is implied by the behavioral note that unread_only inbox reads stop returning marked messages, which tells the agent the consequence of calling it. However, there is no explicit when-to-use vs when-not-to-use guidance or named alternative (e.g., host.msg.inbox for reading).

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?

With no annotations provided, the description carries the full burden and does so well: it discloses that future sends are refused with agent_not_found, that this is byte-identical to a nonexistent address, that the caller can still send to the blocked party, and that block lists are never exposed. These are exactly the non-obvious side effects and information-disclosure traits 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?

Two tight sentences, front-loaded with the core action and then the behavioral consequences. No filler; every clause conveys a distinct fact.

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 mutation tool with no annotations and no output schema, the description is nearly complete on behavior. It does not state what the call returns, but the operational semantics are otherwise well covered.

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 fully. The description implies the target is an address but adds no format or semantic detail beyond what the schema provides, making baseline 3 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 (Block) and resource (an address), and its meaning is immediately distinguishable from the sibling host.msg.unblock. No ambiguity about 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 context for blocking is implied by the description of its effects, but there is no explicit when-to-use guidance or routing against alternatives such as host.msg.unblock. Usage must be inferred.

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?

No annotations are provided, so the description carries the full burden. It discloses that pagination is cursor-based (next_cursor) and that results exclude own sends, which is helpful. But it doesn't state whether this is a read-only operation, pagination stability, or rate limits.

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

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

A single dense sentence front-loads the scope, ordering, and pagination instruction with zero waste. Every clause earns its place.

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

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

For a read/list tool with complete parameter schema but no annotations, the description covers scope and pagination. It omits whether the operation requires auth (tenant_key implies it), whether it's read-only, and what the return shape looks like.

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 all four parameters thoroughly. The description adds pagination semantics (use next_cursor from previous response), going beyond the schema's terse 'Opaque; omit for first page.'

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: retrieves messages across all threads the agent participates in, excluding own sends, ordered oldest first. The scope and ordering distinguish it from siblings like host.msg.thread (single thread) and host.msg.ack (mutating).

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

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

The description implies when the result is filtered (all threads, not own sends) but doesn't explicitly state when to use this versus host.msg.thread. Usage is inferrable from the scope but no alternates are 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?

With no annotations, the description carries the full behavioral burden and does so well. It discloses append semantics ('next seq'), non-failing handling of blocked or contact-closed participants via a refused list, and the specific thread_not_found error behavior for non-participants.

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: it states the core action first, then appends behavioral details and error semantics. Every sentence carries useful information with no filler.

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

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

For a mutating tool with no annotations and no output schema, the description covers participation requirements, append behavior, participant-skipping behavior, and key error semantics. It does not describe the successful return value or authorization details, but the schema covers parameters well and the description is largely complete for safe invocation.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters. The description adds useful behavioral context but does not provide additional meaning for specific parameters beyond what the schema states; 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 and resource: 'Reply in a thread you participate in.' It distinguishes the operation from starting a new thread by requiring participation and describes the append/sequence behavior, so an agent can tell it apart from siblings such as host.msg.send.

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

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

The description clearly gives the core usage condition: you must be a participant in the thread, otherwise thread_not_found is returned. It does not explicitly name an alternative tool such as host.msg.send for starting a new thread, so it lacks full when-to-use/when-not-to-use 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?

No annotations are provided, so the description carries the full burden. It discloses important behaviors: refused recipients are listed in refused rather than failing the call, and from is always the authenticated tenant. However, it omits response shape, permission requirements, and rate limits, making it good but not fully 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 two sentences, with the primary purpose and thread behavior front-loaded, followed by the partial-failure and sender-identity information. Every sentence adds value, with no redundant or filler 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 tool with 7 parameters, no annotations, and no output schema, the description covers core behavior but leaves gaps: it does not explain what the response contains (e.g., message_id), prerequisites for sending (e.g., contact acceptance), or any rate limits beyond the urgent note in the schema. It is adequate but not fully complete 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 coverage is 100% with all parameters described, so the baseline is 3. The description adds minor context (e.g., thread_id's purpose, from always being the tenant) but does not significantly extend the parameter semantics beyond what the schema already provides.

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

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

The description states a specific action ('Send a message to one or more agent-directory addresses') and explicitly distinguishes the thread behavior (new thread vs. adding to existing via thread_id). This separates it from siblings like host.msg.reply and host.msg.thread, making the tool's function 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 for when to use the tool (sending messages, creating/joining threads) but does not explicitly name alternatives or state when not to use it. It implies usage through the thread_id mention, but there is no exclusion or comparison with host.msg.reply or other messaging 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?

With no annotations, the description carries the burden and does well: it discloses ordering (by seq), the pagination model (cursor describing seq to resume after), and a named error condition (thread_not_found when not a participant). It does not state permissions or rate limits, but the key behavioral facts for a read are covered.

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?

Single compact sentence, front-loaded with the primary resource, followed by ordering and the failure condition. No wasted words.

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 tool with no output schema, the description covers the essential behavior: what is returned, order, pagination mechanism, and one error. It could mention that results are limited per call or that participation is required to get data, but the coverage is quite 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 100%, so each parameter already has a description. The description adds only the ordering/pagination concept, which aligns with the cursor semantics. Baseline 3 is appropriate since 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 (read) and resource (every message in one thread), with clear scope: 'you participate in'. Easily distinguished from siblings like host.msg.inbox (all messages) and host.msg.reply.

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?

No explicit when-to-use guidance or discussion of alternatives such as host.msg.inbox for browsing many threads or host.msg.ack for marking read. The participation constraint implies usage but doesn't say when to choose this over siblings.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure for a mutation. It does not state whether the address must currently be blocked, what happens on a non-blocked address, whether the operation is reversible or idempotent, or what permissions/auth are required (the auth nuance is only in the schema's tenant_key field).

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 words, front-loaded and waste-free, but it is under-specified rather than genuinely concise. There is no structural element such as scope, side effects, or return behavior to anchor the agent.

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

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

For a mutation tool with no annotations and no output schema, the description should at least indicate effect and failure modes, but it does not. The schema covers parameters and the header-vs-tenant_key nuance, leaving the behavioral layer entirely undocumented.

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 'address' (the handle or t_... namespace) and 'tenant_key' (auth fallback with header precedence). The description adds nothing beyond that, so the 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 verb ('Remove') and resource ('a block'), which an agent can read as the inverse of the sibling host.msg.block. However, it does not explicitly differentiate itself from that sibling or clarify what kind of block is being removed (messaging block assumed from the host.msg.* namespace).

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?

There is no guidance on when to unblock versus other recovery actions, no prerequisites, and no mention of the block counterpart it reverses. The agent must infer the use case entirely from the name.

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

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

With zero annotations, the description carries the full behavioral burden, and it delivers: it discloses the blocking long-poll nature, the 25s cap, the same-shape return either way, and the precise timeout end-state (empty messages, unchanged next_cursor). What's missing is any statement about side effects — notably whether waiting acks or otherwise mutates messages, which matters given sibling host.msg.ack exists.

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 dense sentences with zero waste. The core behavior and timeout constraint are front-loaded; the return-shape equivalence and timeout end-state follow; the usage context closes it out. Every clause 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?

Given no output schema and no annotations, the description adequately covers behavior (blocking, timeout, end-state) and return shape by cross-reference to host.msg.inbox with named fields (messages, next_cursor). Minor gaps remain: it doesn't specify whether waiting affects ack state (relevant given unread_only and host.msg.ack), but nothing blocks an agent from invoking 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 3 applies. The description adds modest context around cursor ('one past cursor arrives') and timeout_s ('elapses... max 25s'), but these details are largely restated in the schema. No significant new meaning is added beyond what the parameter descriptions already provide.

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: 'Long-poll for a new message until one past cursor arrives or timeout_s elapses.' It clearly distinguishes itself from sibling host.msg.inbox by framing this as the blocking/waiting variant, so an agent can tell them apart without opening either 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 phrase 'for a client with no polling loop of its own' gives clear context for when to choose this tool, and referencing host.msg.inbox implicitly identifies the alternative. However, it never explicitly says 'use host.msg.inbox instead if you poll periodically' — the exclusion is implied, not stated.

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?

With no annotations, the description carries the full burden of disclosing side effects. It explicitly states the immediate consequence – bearer JWTs from the removed issuer stop authenticating – which is the critical behavioral trait for a destructive config change. It doesn't mention reversibility or permission requirements, but the most important runtime impact is disclosed.

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

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

The description is a single sentence that front-loads the action and follows with the key consequence. It contains no filler, repetitive wording, or redundant schema echoes.

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 mutating tool with no output schema and no annotations, the description covers the action, scope, and immediate side effect, which is sufficient for basic invocation. It doesn't address error cases or idempotency, but those are secondary given the schema already covers the parameters.

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 both parameters with 100% coverage, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema – it only refers to the issuer generically and doesn't elaborate on `tenant_key` or value formats.

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 ('Remove') and resource ('OAuth issuers'), and clarifies scope ('this tenant's registered'). The consequence clause ('bearer JWTs from it stop authenticating immediately') further distinguishes it from listing or setting issuers, so an agent can tell it apart from siblings host.oauth.issuers and host.oauth.issuer_set.

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 that this tool targets an already-registered tenant issuer, implying it should be used for revocation rather than registration or listing. It doesn't explicitly name sibling alternatives or exclusion conditions, but the verb and resource make the use case 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?

With no annotations provided, the description carries the behavioral burden. It clearly indicates a read-only listing operation and specifies the returned data fields, including the useful detail that JWKS fetch age is included. While it does not discuss authentication or side effects, 'List' and the field list are sufficient for this non-destructive tool.

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

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

The description is a single, front-loaded sentence with no filler. Every element adds value: the operation, the scope, and the exact returned fields.

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

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

For a simple one-optional-parameter list tool with no output schema, the description provides enough information about what will be returned and the tenant scope. It does not detail response formatting or pagination, but those are minor omissions given the simplicity of the tool.

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

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

Schema description coverage is 100%, so the input schema fully documents tenant_key, including when it is required and how it interacts with the Authorization header. The description adds no parameter-level detail beyond the schema, matching 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 uses a specific verb ('List') with a clear resource ('this tenant's registered OAuth issuers') and names the key returned fields. This clearly distinguishes it from the sibling tools host.oauth.issuer_set and host.oauth.issuer_remove, which are mutation operations.

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

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

The listing verb and tenant scope imply this is the read-oriented counterpart to issuer_set/issuer_remove, but the description does not explicitly state when to use this tool instead of those alternatives. There is no direct when/when-not guidance, so usage is mostly inferred from the resource name and siblings.

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?

With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly. It explains the authentication behavior (bearer JWTs with iss equal, matching aud, verified against jwks_url), implies idempotent register-or-update semantics, states the per-tenant limit, and names a precise error condition (issuer_already_registered).

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 dense, front-loaded sentences: the first states the action and core verification logic, the second adds constraints and an error condition. Every clause earns its place with no redundancy or boilerplate.

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 4-parameter mutating tool with no output schema and no annotations, the description covers the operation's purpose, authentication pipeline, limits, and likely failure mode. The optional tenant_key parameter is fully documented in the schema. It is slightly thin on what the response returns and what exactly 'update' changes, but nothing essential to invoking the tool 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 each parameter is already documented individually. The description adds value by tying the parameters together into the verification flow (iss matches the issuer, audience must match, jwks_url is used for verification) and by explaining uniqueness behavior. It does not add tenant_key semantics, but the schema already covers those fully.

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 'Register (or update) an OAuth issuer for this tenant' – a specific verb and resource – and then details the exact JWT verification semantics (iss, aud, jwks_url). This is clearly distinct from sibling tools host.oauth.issuers (list) and host.oauth.issuer_remove (delete), so an agent can differentiate them 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 clearly frames the use case: register or update an OAuth issuer for tenant authentication, with constraints (max 3 per tenant, uniqueness conflict) that inform decision-making. However, it does not explicitly reference sibling alternatives or state when not to use this tool, so it stops 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?

No annotations are provided, so the description carries the full burden. It discloses a critical behavioral trait: counters are monotonic and a lower value fails validation with nothing written. It also mentions the tenant_key/Authorization header precedence, which is useful behavioral context. It does not describe the return value or error format, but the core behavioral risks are covered.

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: it states the action and resource in the first sentence, then adds the critical monotonic constraint, then points to read-back tools. Every sentence earns its place with no redundancy.

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

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

For a tool with 5 parameters, no output schema, and no annotations, the description covers the essential behavioral constraints (monotonic counters, validation failure, tenant_key precedence) and points to sibling tools for reading back. It could mention what the response looks like or whether partial updates are atomic, but the description is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaning by explaining the monotonic semantics of counters and the merge behavior, which goes beyond the schema's per-key descriptions. However, it does not elaborate on pct/msg semantics beyond what the schema states, so the added value is moderate.

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 ('Report (or merge in)') and resource ('counters and/or pct/msg on a run, by id'), and distinguishes itself from sibling read tools by explicitly pointing to host.runs.get/wait/list for reading back. It is clear what the tool does and how it differs from related tools.

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

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

The description gives clear context for when to use the tool (reporting progress on a run) and mentions the monotonic counter constraint that affects usage. It does not explicitly state when not to use it or name alternatives beyond the read-back reference, but the context is sufficient for an agent to select it appropriately.

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

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

No annotations are provided, so the description carries the full burden and does reasonably well: it declares "Read-only," discloses that unauthenticated callers get the signup step prepended, and describes the returned artifacts (sequence, limits, try_before_call table). It does not discuss rate limits, caching, or whether the example is executable, leaving some behavioral surface uncovered.

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

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

Three sentences, front-loaded with the return contents and zero filler. The first sentence is a heavy noun phrase, but every clause (read-only, when to call, auth behavior) 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?

With no output schema and a simple two-parameter schema, the description fully covers what the tool returns (sequence, limits, try_before_call table), when to use it, and the auth flow. Nothing an agent needs to invoke 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 both `kind` and `tenant_key` are already documented in the schema, including the header-wins-if-both-present rule. The description adds only indirect context (the unauthenticated→signup flow) and does not expand on valid `kind` values or tenant_key sourcing, so it remains 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 gives a specific verb and a concrete resource: it returns the shortest ordered sequence of calls to a working tool of the requested `kind`, plus limits and a try_before_call table, with the caller's namespace substituted in. An agent can tell this apart from the sibling `host.tool_publish` (which it references) and from `signup` 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?

It explicitly states when to call it: "Call this before host.tool_publish if you're not sure what a spec should look like," and gives the auth precondition that unauthenticated callers hit the signup step first. It doesn't cover other scenarios (e.g., looking up limits independently), so it's clear context rather than a full when/when-not decision tree.

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?

With no annotations, the description carries the full burden and does well: it discloses single-use semantics, the specific error codes handoff_token_redeemed and handoff_token_expired, and that the call is unauthenticated because the token itself is the proof. It stops short of describing the exact response shape or any rate limits.

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: the core exchange is front-loaded, followed by failure modes, then the auth model. Every sentence carries new information with no filler.

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

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

For a two-parameter tool with no output schema, the description covers the operation, its preconditions, its failure modes, and the authentication model, and it names the returned value (tenant key). Only the concrete return shape is left unspecified, which is minor here.

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

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

Schema description coverage is 100% and the schema itself documents both parameters, including the subtle rule that tenant_key is only needed without an Authorization header and that the header wins. The description adds no parameter detail beyond that, 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?

States a specific verb (exchange) plus the exact inputs and output: a signup(handoff: true) handoff_token for the tenant key it was issued for. It also names the sibling that produces the token, so an agent can place it in the flow 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?

The description frames the call as the redemption step following signup(handoff: true) and gives the failure conditions (single-use, expiry). It does not explicitly state when not to use it or name an alternative redemption path, but the flow 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal a key prerequisite and the tenant-scoped nature of the operation. However, it does not disclose whether publishing overwrites existing registry data, what permissions are required beyond the named verification, or what success/failure looks like.

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

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

The description is a single sentence that front-loads the action and resource, then appends the prerequisites in a parenthetical. It contains no wasted words and is easy to parse.

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

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

For a state-changing tool with no output schema and no annotations, the description is somewhat thin. It names necessary prerequisites, but it does not explain return values, failure modes, idempotency, or what the registry publish operation changes. This is a clear gap even though the parameter count is low.

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 for tenant_key is 100%, so the schema already explains the parameter thoroughly, including the Authorization header precedence. The description adds no extra parameter-level meaning, which is acceptable under the baseline for 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 uses a specific verb ('Publish') and a clear resource ('this tenant's server.json' to the configured MCP registry). It is unambiguous and distinguishable from siblings like host.tool_publish, which targets a different publishing concept.

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 prerequisites: --registry-url must be configured and admin.tenant_verify_namespace must be run first. This gives an agent actionable preconditions, though it does not explicitly contrast with sibling tools or state when not to use the tool.

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

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

With no annotations, the description carries the full burden and does well: it discloses the sandbox process is killed within ~2s, the run transitions to cancelled, and the exact failure mode for finished runs. It omits auth/permission requirements and whether the operation is idempotent, but the safety-relevant behavior is well covered.

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

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

Two tight sentences, front-loaded with the action and immediately followed by timing and error semantics. No wasted words.

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 mutation tool with no annotations or output schema, the description covers the essential behavior, timing, and failure case. Only auth/permission expectations are left unaddressed.

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

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

Schema coverage is 100%, so both run_id and tenant_key are already fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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 (Stop/cancel) and resource (queued or running job) with precise scope. It clearly distinguishes itself from sibling run tools like host.runs.get, host.runs.wait, and host.runs.purge by naming the run states it acts on.

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?

Specifies the conditions under which it works (queued or running) and when it fails (already-finished run returns run_not_cancellable). It doesn't explicitly name alternative siblings such as runs.purge or runs.wait, so it stops 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the result is only available 'once done' (i.e., non-blocking polling semantics) and that it returns progress, but says nothing about auth requirements beyond the schema, whether polling is rate-limited, or how it differs behaviorally from host.runs.wait.

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

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

A single sentence with the core action and resource front-loaded; the em-dash aside about run origin earns its place as disambiguation. Slightly dense but no filler sentences.

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

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

There is no output schema and no annotations, so the description must cover return semantics; it names status, progress, and result but gives no shape for the status values or progress representation. For a simple two-parameter read tool this is adequate but leaves the agent guessing at the payload structure.

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 (run_id, tenant_key) are documented there, so the schema does the heavy lifting. The description only adds the phrase 'by id', which does not extend 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?

States a specific verb (Read) and resource (one run) and enumerates what is retrieved: status, progress, and result once done. It also ties the resource to its origin (host.tool_call async, scheduled/triggered execution), which cleanly separates it from host.runs.list, host.runs.cancel, and host.runs.purge.

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

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

The description implies usage by explaining where a run id comes from (an async host.tool_call or a scheduled/triggered execution), which tells the agent when it will have an id to query. However, it never names alternatives such as host.runs.wait (blocking) or host.runs.list (enumerate runs), leaving the choice between polling and waiting to inference.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses ordering ('newest first'), tenant scoping, and available filters, but says nothing about the tenant_key auth requirement, pagination/limit ceilings, or what a returned run includes. Some behavioral value added, but the safety/auth profile is undocumented.

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

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

A single front-loaded sentence; the verb+resource+scope lead, and the parenthetical enum lists earn their space by documenting otherwise-absent value sets. No wasted words.

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 read-only list tool with no output schema, and the description covers scope, ordering, and filters, which is most of what an agent needs to call it correctly. Minor gaps remain around pagination and return shape.

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, but the description adds meaning beyond the schema by enumerating the accepted status values (queued|running|done|error|timeout|cancelled) and trigger values (call|job|schedule|event|chain), which the schema leaves as bare strings with no enums.

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 this tenant's recent runs') with scope ('this tenant's'), ordering ('newest first'), and the filterable axes. It is immediately distinguishable from host.runs.get, host.runs.cancel, host.runs.purge, and host.runs.wait.

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?

Usage is implied by the description — an agent infers 'use this to enumerate runs' — but there is no explicit when-to-use, when-not, or routing to siblings like host.runs.get for a single run. Adequate but with a clear gap.

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?

With no annotations, the description carries the full burden, and it does disclose the read-only nature, the 0-based part behavior, the single-part case when the result fit inline, and the not_found failure for overrun n. It does not discuss authorization prerequisites or output format, but the key behaviors are surfaced.

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

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

Three sentences with no filler, and the purpose is front-loaded. The phrase 'reads back parts: 1, n: 0' is compressed to the point of mild ambiguity and could be punctuated more clearly, but the overall description is appropriately sized.

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 simple parameter set and the absence of an output schema, the description adequately covers how parts behave and what happens on overrun. It does not explain how an agent would learn the total part count or what exactly a part contains beyond the n:0 case, but those are reasonably discoverable from the not_found behavior and the tool name.

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

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

The schema already describes all three parameters (100% coverage), so the baseline is 3. The description adds useful n-boundary semantics: 'n past the last part fails with not_found' and n:0 returns the full result when the result fit inline. This is helpful but not a major expansion over what the schema already documents.

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 operation ('Read part n') and resource ('a run's result'), and immediately contrasts with host.runs.get/wait. The not_found boundary and the n:0-holds-full-result rule reinforce the semantics. Minor grammar awkwardness in the second sentence does not obscure the core 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?

It explicitly notes that host.runs.get/wait inline only part 0, which tells an agent when this tool is needed: to read parts beyond the inline part. It also gives the failure condition for out-of-range n. It does not spell out an explicit if-then routing rule, but the context is clear enough.

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

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

No annotations exist, so the description carries the full burden and does reasonably well: it discloses exactly what is destroyed (results of done runs), the resulting post-state (each reads done with result: null, purged: true), and the side effect on quota. It omits irreversibility and permission/tenant requirements, but the mutation semantics are clearly conveyed.

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

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

A single dense sentence that front-loads the destructive action and then the state change and quota effect. No padding, though it is long and would read better split, 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?

For a mutation tool with no output schema and no annotations, the description covers the key behaviors an agent needs: what is deleted, the resulting run state, and the quota benefit. It lacks any note on reversibility or required permissions, which is the main remaining gap.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates before_unix's cutoff semantics without adding syntax or edge-case detail, and never touches tenant_key, so 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 verb (delete/purge) applied to a precise resource (stored results of done runs) with an explicit scope (finished at or before before_unix). The 'done run' qualifier distinguishes it from siblings like host.runs.cancel (running runs) and host.runs.get/list, so an agent can select it 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 explains the motivation ('Frees state_bytes_max quota') which implies when the tool is useful, but never states explicit when-to-use conditions or contrasts with alternatives such as host.runs.cancel or host.state.delete. Usage is inferable but not spelled out.

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