mcphost

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

With no annotations, the description carries the full burden. It discloses one access fact (anonymous callers get the same answer as tenants) but says nothing about whether the call is read-only or side-effect free. Per the schema, omitting tenant_key can implicitly create a brand-new tenant -- a material side effect the description never surfaces.

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

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

Two short sentences, front-loaded with the primary return content followed by the secondary billing-configuration fact. No filler, though the second sentence could be folded in.

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?

An output schema exists, so return values need no explanation, and the single parameter is fully documented. The description covers what is returned and the auth-invariance behavior, leaving only side-effect disclosure as a 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 tenant_key's full semantics (signup binding, header precedence, implicit signup) are already documented in the schema. The description adds nothing about the parameter, which is the expected baseline 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?

The description names the specific resource and its contents -- the plan catalog with price and quotas per plan -- plus a configuration fact (Stripe billing configured on this host). A reader knows exactly what comes back. It does not name or contrast with any sibling, but the subject matter is distinct from the host.* and signup 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?

Usage is only implied: an agent infers it should call this to discover plans and billing availability. There is no explicit when-to-use, when-not-to-use, or alternative named, though the note that anonymous callers get the same answer subtly signals no auth prerequisite.

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 well: it declares read-only, anonymous, no tenant data, and the return fields, plus the edge-case behavior for a misspelt code (tool_not_found with did_you_mean). It stops short of stating rate limits or auth mechanics.

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 dense but well-ordered paragraph that front-loads the main purpose and return shape before the filtering and edge-case details. Every clause earns its place, though the field list is fairly long.

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?

An output schema exists, so return values needn't be re-explained, and the description still tells the agent the two invocation modes and the failure behavior. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds only the filtering behavior of code; it says nothing extra about tenant_key, 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+resource: 'List every error code this host can return', with the exact payload shape enumerated. It is clearly distinguishable from siblings like host.help.search, which deal with documentation rather than error codes.

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 two modes: omit code to list everything, pass code to get one row, and even covers the misspelling case. It gives clear context but never names an alternative tool or states when another sibling would be preferred.

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 disclose non-obvious traits: results are newest-first, only status "received" is returned, and anonymous callers get an empty list. It is silent on auth mechanics, but those are handled thoroughly in the tenant_key schema description rather than here.

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, front-loaded with the action, and each parenthetical carries a distinct, useful fact. Nothing is wasted.

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

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

For a two-parameter read tool with an output schema (so return values need no explanation) and full schema coverage, the description supplies scope, ordering, status filtering, and the anonymous edge case. It is essentially complete, though it could note that the tool is read-only and non-paginated beyond limit.

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

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

Schema description coverage is 100%, and the schema already fully documents limit and tenant_key (including the elaborate binding/auth semantics). The description adds no parameter-level 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 and resource ("List your own feedback") plus scope ("your own") and filter conditions, which is enough to distinguish it from the write-oriented sibling host.feedback.send. It never names that sibling explicitly, so differentiation is inferable rather than stated.

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 "your own feedback" scoping and the anonymous-caller note imply who should call it and what they get, but there is no explicit when-to-use guidance and no named alternative for broader feedback retrieval. Usage 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 full burden and does add real behavioral facts: it is available prior to signup and returns a feedback_id. What it omits is the side effect documented in the schema that omitting tenant_key implicitly signs the caller up as a new tenant, plus any rate or dedupe behavior.

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

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

Two compact sentences with zero padding; the core action and the key constraint (works before signup) are front-loaded. Nothing needs trimming.

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?

A four-parameter tool with a nested context object and an output schema; the return value need not be explained, and the schema covers tenant_key. Still, the description never flags the implicit tenant-creation side effect of omitting tenant_key, which is the single most consequential behavior an agent should know before calling.

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 all four parameters in depth, including the nuanced tenant_key binding rules. The description restates the 2048-byte bound and that context is optional but adds nothing beyond the schema, and never mentions tenant_key.

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: telling "the host's humans" something, i.e. submitting feedback, with the expected inputs named. It distinguishes itself implicitly from the read-side sibling host.feedback.list by being the send path, though it never names that sibling 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?

"Works before signup" is a useful precondition for when this can be called, but there is no explicit when-to-use guidance, no direction on choosing among the kind enum values, and no reference to host.feedback.list or signup as alternatives. 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, the description carries the burden and does well: it declares the operation read-only, anonymous, and free of tenant data, caps output size, and discloses the error contract (anchor_not_found plus did_you_mean suggestions). It does not cover the implicit tenant signup behavior that the tenant_key parameter enables.

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

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

Three dense sentences, front-loaded with the return contract, then invocation, then safety and error behavior. No sentence is 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?

An output schema exists, so return values need no explanation. The description supplies purpose, invocation rule, safety profile, size limit, and error contract, which is everything an agent needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: exact-match semantics for the anchor string and the anchor_not_found/did_you_mean behavior for unknown values. The tenant_key parameter is left entirely to the schema.

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

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

States a specific verb (return) and resource (the documentation section an anchor points at), plus scope details: text capped at 4 KB and the first fenced example. It is clearly distinguishable from host.help.search because it resolves an already-known anchor rather than searching for one.

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 concrete invocation guidance ('Pass an anchor exactly as an error, hint or help entry printed it') and names where anchors come from (an error's `anchor`, a host.help.search hit). It stops short of an explicit when-not or a direct statement telling the agent to use host.help.search first to discover anchors.

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 read-only, anonymous, no tenant data, a response size ceiling (<2 KB), default k=3, and what each hit contains. It does not cover auth header interplay or rate limits, but the schema's tenant_key note covers the former.

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 dense but front-loaded block: purpose, then output shape, then usage guidance. Every clause earns its place, though the single long sentence is slightly harder to scan than two shorter ones.

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?

An output schema exists, so return-value detail is optional, yet the description still summarizes hit contents usefully. The 'anonymous, no tenant data' framing sits slightly apart from the schema's tenant_key signup behavior, but the schema resolves that nuance.

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 q, k, kind, and tenant_key in detail. The description reinforces q's intent ('the error text or import line you are stuck on') and the k default, but adds no format or syntax beyond the schema.

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

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

States a specific verb+resource ('Search this host's own documentation and tool descriptions') and immediately characterizes the output (up to k hits with snippet, nearest runnable example, anchor). The contrast with reading docs files directly makes its role distinct from siblings like host.help.get.

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

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

Gives a clear when-to-use trigger -- 'call it with the error text or import line you are stuck on' -- and an ordering rule ('before reading any docs file'). It does not name the alternative tool (host.help.get) explicitly, so it falls short of full alternative 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?

With no annotations, the description carries the full behavioral burden and does well: it states the call is read-only and never creates a tenant, explains that unauthenticated callers get a worked example with no tenant data, and notes that any other host.*/billing.* call creates a tenant on first use. It does not cover error handling or rate limits on this call itself, but the key side-effect and auth nuances 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 four sentences, front-loaded with what the tool returns, then read-only status, then usage guidance, and finally auth-related behavior. Every sentence adds value, though the first sentence is dense and could be slightly shorter.

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?

An output schema exists, so return values need not be explained. Schema coverage is 100% for parameters. Behavior and usage are well covered. The only missing elements are edge cases like invalid kind or specific error responses, which are minor for this help/quickstart tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description adds no additional syntax or meaning for kind, tenant_key, or retry_after_s beyond what the schema provides. Baseline 3 is appropriate 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?

The description states a specific verb (Return) and a clear resource (shortest ordered sequence of calls to a working tool of `kind`, plus limits and a try_before_call table). It distinguishes itself from siblings by explicitly referencing host.tool_publish and the broader host.*/billing.* context, so an agent can tell what it does without opening the schema.

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

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

It names the alternative (host.tool_publish) and the condition that selects this tool ('Call this before host.tool_publish if you're not sure what a spec should look like'). It also implicitly guides usage for unauthenticated callers versus other host.*/billing.* calls that create tenants. No inference 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?

With no annotations, the description carries the full behavioral burden: it declares unauthenticated operation, single-use redemption, the handoff_token_redeemed failure code on second use, the handoff_token_expired failure code past expiry, and that the token itself is the proof. This is rich behavioral disclosure well beyond the 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?

Three tightly written sentences, front-loaded with purpose and followed by the critical lifecycle and failure semantics. Every sentence earns its place with no filler or repetition.

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

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

For a two-parameter tool with no annotations and an output schema, the description supplies the needed auth, lifecycle, and failure context. Return values are covered by the output schema, and tenant_key nuances are covered by the schema description.

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 adds no parameter syntax, format, or constraint detail beyond what the schema already documents for handoff_token and tenant_key. 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?

States a specific verb (Exchange) and resource (signup(handoff: true) handoff_token for the tenant key), making the operation distinct from the sibling signup tool. The relation to signup's handoff mode identifies the exact input and outcome without requiring the schema to be opened.

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?

Clearly triggers on a handoff_token returned by signup(handoff: true) and gives failure conditions for redeeming it again or after expiry. It does not explicitly compare to alternatives such as host.resume or host.whoami, so it stops short of a 5.

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

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

No annotations, so the description carries the full burden and does so well: it discloses the 4096-byte cap, the truncation contract via 'truncated', that the operation is read-only, and the unauthenticated path (onboarding block, no tenant created). Auth/binding nuance is further handled in the 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?

Front-loaded with the payoff (what you get in one call), then truncation handling, then safety/auth notes. Dense but every clause carries information; the parenthetical enumerations make it slightly run-on but not wasteful.

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?

Output schema exists, yet the description still frames the return shape and the truncation escape hatch, plus auth behavior. For a resumption/orchestration tool with one optional param, 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 description coverage is 100%, and the tenant_key schema text already explains binding, signup, header precedence, and implicit signup. The description adds no additional parameter 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 ('Resume where you left off') and enumerates exactly what comes back: tools with last call status, unfinished runs, newest notes, host changelog, and a suggested next_call. It distinguishes itself from siblings by naming the per-section tools (host.tool.list, host.runs.list, host.note.list, host.changelog) an agent would use instead.

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?

Clear context for when to use it (to resume in one call) and explicit routing to the section-specific tools when output is truncated. It doesn't explicitly contrast with host.state.get or host.state.list, which are the closest-looking siblings, so it stops short of full when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It does disclose one genuinely useful trait — a missing key returns found:false rather than an error — but says nothing about permissions, tenant binding requirements, or what happens when an implicit tenant is created, all of which are behaviors an agent would want surfaced at this level.

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

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

Two short sentences, zero filler, and the core operation is front-loaded ahead of the not-found caveat. Every sentence earns its place.

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

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

An output schema exists, so return values need not be spelled out, and the parameter semantics are fully documented in the schema. The description is nearly complete for a simple getter, though it does not touch the non-obvious tenant-binding/implicit-signup implications that an agent could otherwise miss.

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%, including detailed prose for tenant_key and end_user, so the schema already does the heavy lifting. The description adds only the namespace-scoping phrase, 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 ("Read") and resource ("one key from this tenant's key-value state namespace"), which is enough to separate it from host.state.list (many keys) and host.state.set (write). It does not explicitly name those siblings, so it stops short of the 5 benchmark, but the scope word "one" conveys the distinction.

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

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

Usage is implied by the read-one-key framing and the not-found behavior signals when this is the correct call, but there is no explicit when/when-not guidance or naming of alternatives such as host.state.list or host.state.set. Adequate minimum, 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose that current values are returned (not just keys) and that results can be narrowed by prefix, and 'List' implies a read operation, but it says nothing about permissions, rate limits, or pagination behavior.

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

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

A single front-loaded sentence with no filler; the resource and its scope lead, with the optional filter trailing. 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?

With a 100%-covered schema and an output schema that documents return values, the description need not explain formats or fields. It is adequate, though it omits any mention of the implicit tenant-binding/signup side effects that the tenant_key schema documents.

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 limit, prefix, end_user and tenant_key are already fully documented in the schema. The description only restates the optional prefix filter and adds no syntax or semantics beyond what the schema provides, making 3 the correct 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 (List), resource (keys in this tenant's key-value state namespace) and scope (this tenant's, optional prefix filter), plus the useful detail that values are returned alongside keys. It does not explicitly differentiate from the sibling host.state.get/host.state.set, but the name and scope make the distinction inferable.

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

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

The description notes the prefix filter is optional but gives no when-to-use guidance, no conditions for choosing this over host.state.get, and no prerequisites. Usage must be inferred from the name and schema 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?

With no annotations, the description carries the full behavioral burden. It helpfully discloses quota-failure behavior ('state_quota_exceeded' and 'writes nothing'), but it does not say whether writing an existing key overwrites its prior value, whether the write is atomic/idempotent, or what permissions are required.

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

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

Two sentences, front-loaded with the core action and followed by the most important failure mode. 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?

The output schema and fully described input schema mean return values and parameter details need not be in the description. The description covers purpose and a key failure mode, though it omits overwrite semantics that matter for a mutation tool with no annotations.

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 key, value, dry_run, end_user, and tenant_key semantics. The description adds no parameter-level meaning beyond repeating that the value may be any JSON value; baseline 3 applies when the schema does this much work.

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 ('Write') and resource ('one key in this tenant's key-value state namespace'), and implicitly distinguishes itself from read-oriented siblings like host.state.get and host.state.list. The value-type and quota clauses add useful scope without obscuring the core action.

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

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

The description does not state when to use this tool versus alternatives such as host.state.get, host.state.list, or dry-run mode. It gives no when-not-to-use guidance, leaving the agent to infer usage from the write verb and sibling 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, the description carries the full behavioral burden and does well: it discloses that this is a real metered call that counts toward host.usage and appears in host.tool_logs, describes the async return shape {run_id, status}, and notes that an unknown version is an argument error. It omits behavioral detail on budget refusal and tenant_key side effects, which are only in the 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?

A dense but well-structured paragraph that front-loads the core purpose and equivalence to namespaced invocation before elaborating options. Every sentence adds some value, though a few clauses on async/version duplicate schema content and could be trimmed.

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

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

For a complex 7-param tool with nested budget and an output schema, the description covers the essential invocation semantics, metering, and async/version behavior without needing to explain return values (output schema exists). The one gap is that dry_run, budget, and tenant_key semantics are left entirely to the schema, but overall it is complete enough to call 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 all seven parameters thoroughly (including nested budget fields). The description's notes on async and version largely restate what the schema says, adding only the local-vs-namespaced name framing. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ("Invoke") and resource ("a tool this tenant has already published, by its local name") and explicitly equates it to calling by namespaced name, so the agent understands the exact operation. It also names the sibling host.tool_test as the contrasting tool, making it distinguishable 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?

Gives a clear condition for use ("for a session that has no way to see its own namespaced tool name yet") and an explicit contrast with host.tool_test (which does not meter). It also routes long-running calls to async mode and version pinning to host.tool_history. It does not cover the dry_run/host.estimate alternative, leaving one notable 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. It usefully discloses the name regex, the rejection behavior (failing field plus corrected example), and Python's mcphost sandbox imports. However it never states what publishing does to an existing tool of the same name (overwrite vs conflict), nor the mutation/permission profile, which are the traits an agent most needs here.

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

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

Purpose is front-loaded, followed by prerequisites, then environment and error details, in four dense sentences with no filler. Every clause carries actionable information.

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

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

Output schema exists, so return values need no explanation, and the schema fully documents the kind-specific spec shapes and error families. Combined with quickstart and tool_test pointers, the description is nearly complete; the one real gap is the republish/overwrite semantics of a mutating publish call.

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% across all 9 parameters, so force, scopes, tags, dry_run, tenant_key and visibility are already well documented in the schema. The description adds only the kind examples and a Python sandbox note, both of which the schema also touches, so the baseline 3 is correct.

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

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

States a specific verb and resource: publish a tool of a registered kind, scoped to the tenant namespace, and names the kind enum as the source of valid values. An agent can distinguish it from host.tool_test and host.tool_call purely from this sentence.

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

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

Gives explicit sequencing and alternatives: call host.quickstart(kind) first for an example spec and the publish-to-call sequence, and try host.tool_test before a real call. The condition that selects each sibling is stated, not implied.

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

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

No annotations are supplied, so the description carries the full burden; it does disclose the key behavioral fact that the tool keeps running in this tenant's sandbox with this tenant's own secrets and is reached as <namespace>.<name>. That is genuinely useful context, but it omits auth/permission requirements, whether the share is idempotent or revocable, what happens to existing grants, and the rate-limiting/scope behavior that governs what a grantee can actually do.

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, zero filler, with the recipient modes front-loaded and the hosting/namespace model following as necessary context. Every clause carries information an agent cannot get from the name alone.

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?

An output schema exists, so return values need not be explained, but for a 9-parameter mutation tool with no annotations the description is thin: it never covers the unlisted/url visibilities, the scopes grant model, per-caller rate caps, or the fact that the definition is deprecated in favor of host.tool.share (2026-12-31). Adequate for the core share semantics, not complete.

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

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

Schema description coverage is 100%, so the baseline is 3; every parameter (tags, group, scopes, expose_spec, rate_per_hour_per_caller, tenant_key) is already documented in the schema. The description adds meaning only for visibility/group, leaving scopes and the exposure controls entirely to the schema.

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

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

States a specific verb (share) and resource (one of this tenant's published tools) plus the two recipient modes, so the agent knows exactly what the call does. It implicitly depends on host.tool_publish having run first but never names that sibling or contrasts sharing with publishing/forking, so sibling differentiation is only partial.

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

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

Gives the conditional for two modes: 'everyone (visibility: public)' vs 'a named group this tenant owns (visibility: group, group: <name>)', which is real routing guidance. However, it ignores the other two enum values the schema allows (unlisted, url) and offers no exclusions, prerequisites (public needs a passing dry run), or alternatives such as host.tool_publish or host.tool_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 full burden, and it does disclose the key behavioral trait: writes are rolled back in dry_run. It also names the verdict states, which tells the agent what to inspect. It omits auth/tenant implications and what a failed verdict means in practice.

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 with the core action front-loaded and no filler; the verdict enumeration and rollback note are packed efficiently. The quickstart pointer is short and actionable.

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

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

An output schema exists, so return values need not be explained, and the schema fully covers the four parameters including nested objects. The description covers the essential contract (dry-run, rollback, verdict); only the fixture/chaining story is left entirely to 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 description coverage is 100%, so the baseline is 3; every parameter including args, fixtures and tenant_key is already documented in the schema. The description adds little beyond re-stating that the tool is selected 'by name'.

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 ('Dry-run a published tool by name') plus the outcome vocabulary (pass/will_fail/unverifiable), which lets an agent distinguish it from the real-call sibling host.tool_call. It stops short of naming that sibling explicitly, so differentiation is implied rather than stated.

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 'Dry-run' and the pointer 'see host.quickstart'. There is no explicit statement of when to prefer this over host.tool_call, nor any exclusion such as 'cannot dry-run unpublished 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 full behavioral burden, yet it only restates the return content. It does not disclose the significant side effect documented in the schema — that omitting tenant_key on a connection with no Authorization header silently signs up a brand-new tenant — nor does it mention auth expectations or read-only status. The one behavioral fact an agent most needs is absent from the description.

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 core action front-loaded and no filler. Every phrase (calling tenant, key_age_s, key_rotated_at) 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented in the schema. The description supplies adequate purpose context for a 1-param read tool; only the behavioral side effect and auth model live solely in the schema, which is a minor completeness gap rather than a functional one.

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 tenant_key description is unusually thorough (header precedence, implicit signup, binding from signup/redeem). The tool description adds nothing about the parameter, so the schema does all the work — 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 and resource: 'Return the calling tenant's identity' with the additional scope of credential-hygiene fields. It is clearly distinct from mutation siblings like host.state.set or signup, but it never explicitly contrasts itself with the closest read siblings (host.state.get, host.resume), so it stops short of full sibling differentiation.

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

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

Usage is implied by 'for auditing credential hygiene' — an agent can infer this is a read of its own identity for key-age checks. However, there is no when-to-use/when-not guidance, no prerequisites, and no named alternative (e.g., vs host.state.get for tenant state), so the routing decision 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 full burden and does well: it declares the call unauthenticated, explains that handoff_token is short-lived and single-use, and gives the security rationale (a leaked transcript carries a dead credential). It does not mention rate limits, tenant quotas, or what happens on duplicate names, so it is strong but not exhaustive for an unannotated 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?

Front-loaded with the core purpose and the primary caveat in the first sentence, with no filler. The final sentence about the raw-key path staying supported is a useful but slightly padded reassurance.

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?

No output schema exists, so the description must describe returns, and it does: a bearer key plus namespace, or a handoff_token, plus the mention of the onboarding field on implicit creation. An agent has enough to call correctly and to decide between handoff modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to handoff: why it is recommended, that the token is single-use, and that it must be redeemed via host.redeem. The name and source parameters are left to the schema, which already documents them thoroughly.

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 ('create a tenant') plus what is returned ('bearer key and namespace'), and pins down the exact audience: a client that cannot keep a session across calls. It is clearly distinguished from the implicit-tenant behavior of sibling host.*/billing.* calls.

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

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

Explicitly says most clients never need this and names the alternative path (any fresh host.*/billing.* call creates a tenant implicitly and returns /u/<secret>/mcp in the onboarding field). It also recommends the handoff:true variant and names host.redeem as the redemption step.

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