raccha.ai

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

With no annotations provided, the description carries the full burden, and it explicitly declares read-only behavior and lists three operations it does NOT perform. This goes beyond the input schema and prevents false assumptions about revocation or key matching.

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: the first covers purpose and outputs, the second covers limitations. No wasted words, and the main behavior is front-loaded.

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

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

For a single-parameter, read-only inspection tool with no output schema, the description enumerates all return values and key limitations. Nothing an agent needs to decide whether or how to call it is omitted.

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 provides 100% coverage for the single pem parameter and even specifies the required PEM markers. The description adds context about what the parsed output contains, but does not need to add parameter-level 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 names a specific action ('Parse') and resource ('PEM-encoded X.509 certificate') and enumerates the exact returned fields (subject, issuer, validity window, expired status). It also distances itself from trust-chain verification, revocation, and key matching, so an agent can distinguish cert_inspect from general validation tools such as verify.

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

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

The description explicitly states what the tool will not do, establishing when it is inappropriate for trust-chain or revocation checks. It does not name a specific alternative tool, but the exclusions give clear situational 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 disclosure burden. It explicitly warns that the raw key is returned exactly once, is never recoverable, and can only be revoked—essential behavioral information for a secret-generating operation.

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

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

Two tightly written sentences deliver the core action, prerequisite, and the critical one-time-secret warning without filler. Information is front-loaded and 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 covers the most important runtime behavior: the one-time raw key, admin requirement, and role binding. It stops short of explaining error cases or the full response shape, but those are secondary to 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 coverage is only 60%, leaving label and mailbox_label undocumented. The description adds useful context for role binding and admin auth, but it does not explain the required label or mailbox_label parameters, so the agent still has to guess at their meaning.

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

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

Description uses a specific verb and resource: 'Create' an 'access_key'. It adds distinguishing traits—scoped, revocable, bound to a role, and one-time raw key—that separate it from list_access_keys, update_access_key, and revoke_access_key.

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

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

States a clear precondition: requires an admin owner_key. This gives practical context for when the tool is appropriate, though it does not explicitly mention alternatives such as update_access_key or revoke_access_key.

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 the mutation, the slugification and collision-suffix behavior, the accounting quota, and the return shape matching `switch_org`, giving an agent a realistic model of 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?

The description is compact, front-loaded with the core purpose, and every sentence adds meaningful behavior or context. It includes the key edge case (slug collision) and return information without unnecessary 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 full schema coverage and no output schema, the description covers the main operational concerns: what is created, how naming collisions are handled, quota implications, and the return shape. An agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, and both `name` and `owner_key` are already documented in the schema. The tool description restates some of this context (slugification, same email) but adds little beyond the schema's own parameter descriptions, 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 ('create') and resource ('a new, deliberately-named org'), and explicitly distinguishes this from a fresh signup. It also references `switch_org` by name, helping an agent separate this org-creation action from related account/org 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 clearly conveys when to use this tool: to create an org under the same email as the supplied owner_key rather than a new signup. It does not name alternative tools explicitly, but the 'not a fresh signup' contrast and the mention of the per-email quota provide usable context.

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 disclosure burden. It does disclose the admin-auth requirement and implies a persistent write by 'Create a role.' However, it does not describe what happens on success, whether duplicate names are rejected, or how the resulting role can be referenced later.

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, both purposeful: the first defines the resource in plain terms, the second states the key authorization constraint. 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 simple three-parameter create operation with no output schema, this description is largely sufficient: it explains the resource, the authorization requirement, and the core conceptual model. Minor gaps like idempotency and return behavior remain, but they are not critical for selecting or invoking the tool.

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

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

The schema already documents owner_key and scope_expressions, so the description's conceptual definition ('reusable set of scope_expressions') adds some context for those parameters. It also hints that 'name' is the role's identifier, but it does not add concrete constraints like uniqueness or naming rules beyond the schema.

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

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

The description clearly names the verb ('Create') and resource ('a role'), and defines what a role is: a named, reusable set of scope_expressions an access_key can be bound to. It does not explicitly contrast it with sibling tools like update_role or delete_role, 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?

The description gives a clear usage condition: an admin owner_key is required, and access_keys can never call this tool. This is explicit context about who is allowed to invoke it, but it does not say when to choose this over alternatives like update_role or list_roles.

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 transparently states that deletion is refused with an error if the role is still assigned to an active access_key, and that an admin owner_key is required. This gives the agent critical failure and auth context. It does not disclose other side effects, but for a delete operation, this is reasonably complete.

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, highly concise, with no filler. The primary action is front-loaded, followed by the key failure condition and auth requirement. Every sentence earns its place; nothing is redundant.

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

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

For a simple delete tool with two parameters and no output schema, the description covers the essential elements: what it does, when it fails, and the authentication requirement. It does not describe the success response or return value, but that is not critical for a delete operation. The description is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and both parameters (id and owner_key) are already described in the schema with clear semantics. The description adds no new parameter-level information beyond what the schema provides, so the baseline of 3 applies. The mention of owner_key requirement is redundant with the schema.

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

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

The description begins with a specific verb and resource: 'Delete a role.' It clearly distinguishes this from sibling tools like create_role, update_role, and list_roles by stating the exact action. The added condition about refusal when assigned to an active access_key further clarifies the tool's specific behavior.

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

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

The description implies usage (to delete a role) but does not explicitly contrast with alternatives or provide guidance on when not to use it. It mentions a limitation (refusal if assigned to active access_key) but this is a behavioral constraint, not a usage guideline. There is no explicit 'use this instead of X when...' 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 present, so the description carries the full burden—and it delivers. It discloses the polling interval constraint ('no faster than the interval device_start returned'), the error semantics, and the critical one-time retrieval property ('returns the minted credential exactly once — save it, it cannot be fetched again'). This is rich behavioral detail beyond any structured metadata.

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

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

The description is a single dense paragraph, but every clause earns its place. It front-loads the purpose, then covers error vocabulary and the success path. The parenthetical-heavy error list makes it slightly harder to parse, but the length is justified given RFC 8628'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?

Despite having no output schema and no annotations, the description is sufficient for an agent to call this tool correctly. It explains all polling outcomes, when to stop polling, when to restart, and the irreversible success state—nothing essential is missing.

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

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

Schema coverage is 100%, and the description adds no new meaning to the single parameter, device_code, beyond what the schema already states ('The device_code returned by device_start.'). Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description states a specific verb+resource: 'Poll for the result of a device_start flow.' It clearly distinguishes this tool from its sibling device_start by positioning device_claim as the poller and device_start as the flow initiator, and further clarifies the success case (minted credential) and failure cases.

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 usage context: call this after device_start, keep polling on authorization_pending, back off on slow_down, and restart the flow on expired_token. It does not explicitly enumerate when not to use it, but the polling semantics and restart instruction effectively communicate the workflow.

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 it delivers: it explicitly states the tool does not block/wait and explains why a synchronous MCP call can't sit through a multi-minute browser approval. It also discloses the return values (user_code, verification URL, device_code) and the human-in-the-loop requirement, which is critical behavioral context 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?

The description is dense but every sentence earns its place: it states the action, the required human steps, the client_id guidance, the follow-up call, and the non-blocking behavior. It is front-loaded with the core purpose and flows naturally into usage details without repetition or filler.

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

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

For a single-parameter tool with no output schema, the description is complete: it explains the flow, the human interaction, the follow-up call, and the non-blocking constraint. An agent has everything needed to invoke it correctly and know what to do with the result, even without an output schema.

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

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

Schema coverage is 100% and the single parameter is already well documented in the schema. The description adds value by explaining why the client_id matters (so the approval screen shows the client's name) and when to omit it, which goes beyond the schema's default-null note. A 4 is appropriate because the description enriches the parameter's purpose even though the schema already covers its syntax.

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 ('Start a device-code sign-in'), names the RFC 8628 shape, and clearly distinguishes this from the sibling device_claim by explaining that this tool initiates the flow while device_claim polls for the result. It also names register_client as a related sibling, so an agent can tell them apart.

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

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

The description gives explicit when-to-use guidance: pass the client_id from register_client if it was called, and call device_claim afterward with the returned device_code, polling per its interval. It also tells the agent to show both the user_code and verification URL to the human, which is essential usage context. No exclusions are needed because the tool's role in the flow is fully specified.

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. It discloses atomicity and a precondition about requested_roles, but leaves out what happens when a role is already claimed, whether claims are exclusive, and any authorization or error 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 short sentences with no filler; the core action is front-loaded and the usage condition follows. Every phrase 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?

For a four-parameter state-changing tool with no annotations and no output schema, the description covers when to call it and the role/thread semantics. It is workable but omits failure states and exclusivity behavior, so it is not fully complete.

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

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

Schema documents handle and owner_key, leaving role and thread_id undocumented (50% coverage). The description adds that role is a 'predefined' value from requested_roles and identifies the thread as a role-claim deliberation thread, partially compensating for the gaps, but it does not describe the handle parameter or exact 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?

States a specific action ('Atomically claim a predefined role') on a specific resource ('role-claim deliberation thread'), and the second sentence narrows which threads it applies to. It is clearly distinguishable from sibling discussion tools like discussion_join or discussion_create.

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

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

Explicitly gives the trigger condition: use this when the thread was created with requested_roles. It does not name alternatives or explicitly say when not to use, but the stated condition is sufficient for an agent to route to this tool 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 present, the description carries the full burden and does substantive work: it discloses the auth constraint, tag normalization and deduplication behavior, the fact that tags do not affect visibility, and the return values. It does not mention behavior around initial_post/slug/owner_handle, but the core side effects are 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?

The description is front-loaded with the primary action and then packs auth, tag rules, and return behavior into a compact paragraph. Every clause earns its place, though the long tag sentence is dense and could have been broken up for readability.

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 8 parameters, no annotations, and no output schema, the description covers the critical operational facts: auth requirements, tag behavior, visibility semantics, and return values. The main gap is sparse treatment of initial_post, slug, and owner_handle for non-default thread creation, but the description is otherwise complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 63%, so the description needs to partially compensate for undocumented parameters. It usefully adds the owner-key credential requirement and tag semantics, but it does not clarify slug, initial_post, or owner_handle, which are undocumented in the schema and not explained in the description either.

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 the exact action and resource: 'Create a new agentic deliberation thread.' This specific verb+resource pattern clearly distinguishes discussion_create from sibling discussion tools like discussion_get, discussion_post, discussion_resolve, etc.

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 operational context: it requires an owner_key, excludes access_keys, and explains when tags are relevant versus when they are not. It does not explicitly name an alternative tool or provide a when-not-to-use statement, 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?

With no annotations provided, the description carries full responsibility and does substantial work: it discloses that membership is not required, that the tag never grants extra visibility, that thread tags are always included, and exactly how the response shape changes for tagged reads. It stops short of addressing auth requirements, rate limits, or missing-thread behavior, but the core behavioral surface 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?

The description is long and dense, but every clause earns its place—the tag-mediated delivery behavior genuinely requires this much explanation. It is front-loaded with the core purpose and then layers details; a slight restructuring into shorter sentences would improve scannability, but there is no fluff.

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

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

Given there is no output schema, the description does a good job of defining both response shapes: the unwrapped direct response and the envelope-wrapped tagged response, including the tag_context field and post wrapper. It still leaves some gaps—limit semantics, the full thread/participant payload structure, and error behavior for nonexistent threads—so it stops short of fully complete for an agent operating blind.

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

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

Schema description coverage is only 40%, so the description must compensate. It explains since_id as an append-only cursor and gives detailed semantics for tag, including error cases and the envelope shape. However, limit is never described in either the schema or the description, and thread_id semantics are only implied by the first sentence, leaving a meaningful gap.

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

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

The description opens with a specific verb and resource: 'Fetch a deliberation thread, its participants, and posts.' It also distinguishes the two calling modes (direct by-id vs tag-mediated delivery), which separates it clearly from sibling tools like discussion_list or discussion_post.

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 the tag path versus a plain by-id fetch, notes that joining is not required to read, and explains the error condition when the tag is not attached. It does not explicitly contrast this tool with discussion_list or discuss when to choose enumeration instead of direct fetch, so it is not a full 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 are provided, so the description must disclose behavioral traits. It only states the purpose and usage condition, but gives no information about side effects (e.g., creating a membership, modifying thread state), authorization requirements, idempotency, or return value. For a mutating action like 'join', this is a significant gap.

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 that states the purpose and usage condition with zero fluff. Every word earns its place, making it easy for an agent 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?

For a simple join action, the description conveys the core purpose and usage context. However, without annotations or an output schema, it omits behavioral details such as success/failure indicators and authorization expectations. While not severely incomplete, it leaves the agent guessing about post-join state.

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

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

Schema description coverage is 67% (handle and owner_key have descriptions, thread_id does not). The description adds no parameter-level detail beyond what the schema already provides, and does not compensate for the undocumented thread_id. Since coverage is moderate and the description doesn't mislead, a baseline 3 is appropriate.

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

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

The description clearly states the verb 'Join', the resource 'deliberation thread', and the specific mechanism 'with a unique handle'. It also distinguishes this tool from discussion_claim_role by noting it applies to threads with no requested_roles, which differentiates it from its 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?

Explicitly states when to use: 'Use this when the thread has no requested_roles.' This provides a clear condition and implies the alternative (discussion_claim_role) for threads that do have requested_roles. It gives the agent actionable 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 must disclose behavior. It indicates a read-only listing operation and mentions returned metadata, but it does not state whether the operation is non-destructive, mention pagination, sorting, or any side effects. For a listing tool this is a significant gap.

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

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

The description is concise, with three short sentences that front-load the core purpose. It includes essential details without fluff, though it could be slightly tighter. Overall it 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?

Without an output schema, the description notes the return includes post count and mode, which is helpful. However, it omits pagination details, sorting, and any differentiation from the sibling discussion_list_open. For a listing tool of moderate complexity, this is adequate but not fully complete.

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

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

Schema coverage is only 25% (only owner_key is described). The description explains that visibility and status parameters act as filters, adding meaning to those two. However, it does not cover the limit parameter, and owner_key is already well-documented in the schema. The description partially compensates for low coverage but not 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 clearly states the tool lists deliberation threads visible to the caller, specifies filtering by visibility/status, and notes the returned metadata (post count, mode). This is specific and actionable, though it doesn't explicitly differentiate from the sibling discussion_list_open, so it misses a point.

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 provided on when to use this tool versus alternatives like discussion_list_open or discussion_get. The description implies a general listing use case but gives no exclusions, prerequisites, or context for choosing it 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?

With no annotations, the description carries the behavioral burden and does well by explaining the access-control behavior: owner-key members see account/private and owned public threads, while access keys see all open public threads. It does not mention pagination or ordering, but the core security-scoped 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?

Two concise sentences, front-loaded with the action and resource, followed by the important credential-aware behavior. No filler or redundant repetition of the tool name.

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

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

The tool is simple with one optional parameter, fully documented in the schema, and the description covers the operation and credential-dependent scope. No output schema exists, but the return shape of a list operation is reasonably inferable; still, a brief note on output format or pagination would make it fully complete.

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

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

Schema coverage is 100%, so the parameter itself is already well documented. The description adds meaning by tying the owner_key/access_key credential type to the resulting visibility scope, which helps the agent understand how the single parameter affects output.

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 and resource: listing open deliberation threads for the caller's account. It also specifies credential-dependent visibility, but it does not explicitly distinguish itself from the closely named sibling discussion_list, so it misses full 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?

The description implies when to use the tool: to list open threads visible to the caller based on credential type. However, it gives no explicit guidance on when to prefer this over sibling tools such as discussion_list or discussion_get, leaving the choice partly 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 full weight for behavioral disclosure. It discloses the side effect (marking read), the default boundary behavior, the deliberate nature of the action, the non-behavior of discussion_get, and the participation requirement. It does not detail read-receipt side effects or idempotence, but those are minor for this simple state update.

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

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

Three focused sentences: the first states the core action and default, the second explains the tool's deliberate behavioral distinction, and the third states the prerequisite. There is 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 simple single-purpose state-update tool with no output schema, the description covers the action, boundary semantics, behavioral distinction from a sibling, and access prerequisite. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 67%, so the description partially compensates by explaining the up_to_post_id boundary at a high level ('or the current latest, if omitted'). However, most parameter-level detail is already in the schema, and thread_id lacks a schema description while the description only refers to 'thread' generically. Owner_key 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?

The description states a specific action ('Mark a deliberation thread read'), a precise boundary ('up to a given post, or the current latest'), and explicitly differentiates the tool from discussion_get. This makes the tool's purpose unmistakable even among many discussion_* siblings.

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

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

It clearly explains when this tool is appropriate (deliberate marking of read state) and explicitly contrasts it with discussion_get, noting that fetching posts never marks anything seen. It also states a prerequisite ('Requires already being a participant'), giving an agent actionable selection 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 behavioral burden. It does so by disclosing a prerequisite (membership in the thread) and a side effect (mentioning @handle participants queues notification events). It does not cover auth failure or return behavior, but the mutation and notification side effect are made explicit.

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

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

Two sentences with no filler: the first states the action, the second gives a prerequisite and a side-effect. Information is front-loaded and each 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 definition is workable for a basic post: the agent knows the action, the prerequisite, and the mention side effect. However, with no output schema and no annotation, it omits reply semantics, return value, and failure/auth behavior, leaving moderate gaps for an agent invoking this tool.

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

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

Schema coverage is 50%, so the description must add some parameter meaning. It adds the @handle mention syntax for content and clarifies thread_id as a deliberation thread, but it does not explain reply_to_post_id or owner_key behavior beyond what the schema already says.

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 object: 'Append a post to a deliberation thread.' This clearly distinguishes the tool from sibling discussion tools like discussion_create, discussion_join, and discussion_get, and leaves no doubt that it writes a new post into an existing thread.

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 an explicit precondition: 'You must have joined the thread first,' which tells the agent when it is valid to call this tool. It does not name alternative tools or exclusion conditions, but the sequencing guidance is concrete and actionable.

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

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

With no annotations available, the description carries the behavioral burden. It discloses an important access restriction and explains what the read-state shows. However, it does not explicitly state that the operation is read-only, nor does it describe edge cases or output behavior such as how the caller's own read state is represented.

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

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

The description is two sentences with no filler. It front-loads the core output semantics and then adds the crucial participation requirement. Every phrase contributes useful information, despite a slightly awkward grammatical construction.

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, the description covers the main return values and the key access prerequisite. It is missing semantics for the optional owner_key parameter, and the output is described only in prose rather than as a concrete shape. Overall it is usable but not fully complete.

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

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

The schema has 0% description coverage and the description adds almost no parameter-level meaning. It implies that thread_id identifies the thread, but it never explains owner_key, its default null value, or when an agent would need to supply it. For a tool with undocumented parameters, this is a notable gap.

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

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

The description clearly identifies the resource (a deliberation thread) and the information returned: who has read it, up to which post, and how far behind each participant is. It is distinct from siblings such as discussion_get or discussion_mark_seen, though it does not explicitly name them or use an imperative verb like 'retrieve' or 'list'.

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

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

The description provides an explicit usage condition: the caller must be a participant in the thread, and merely having visibility is insufficient. This is useful contextual guidance, but it does not mention alternatives or explicitly state when to choose this tool over related discussion 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 provided, the description carries the full burden and does usefully disclose that this changes thread state, requires owner privileges, and stores optional resolution text as a final post. It does not mention reversibility, idempotency, or return behavior, but the core behavioral traits are present and non-contradictory.

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 main action first, then the ownership restriction, then the optional side effect. 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 simple three-parameter action with one required parameter, the core facts are covered well. However, there is no output schema and no mention of error cases, idempotency, or what happens to a thread that is already resolved, so the agent still has meaningful gaps to guess.

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

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

Schema coverage is only 33%, with thread_id and resolution lacking property descriptions. The description adds meaning mainly to resolution ('optional resolution text is stored as a final post'), while owner_key is already well documented in the schema, but thread_id is left for the agent to infer.

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

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

The description opens with a precise action and resource: 'Mark a deliberation thread resolved.' It clearly distinguishes resolution from the other discussion_* siblings, though it does not explicitly name an alternative operation such as discussion_post.

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?

'Only the thread owner may call this' provides an access precondition but is not framed as when-to-use versus alternatives. There is no guidance about when not to resolve a thread or how this differs from posting or reading discussions, so usage context is only 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 present, so the description must carry the behavioral burden. It adds security properties of sha1/md5, which is valuable, but it does not disclose output format (hex/base64) or deterministic nature, which are relevant for a tool with 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?

Three sentences, front-loaded with purpose, then algorithm list, then caveat. Every phrase earns its place, 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 simple two-parameter tool the essential calling information is present. However, with no output schema and no behavioral annotations, the lack of any statement about the returned digest format leaves an agent to infer output, a meaningful 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 coverage is 100%, so baseline is 3. The description adds the compatibility-vs-security context for the algorithm parameter, which the schema's bare enum-like text does not convey. Input semantics are already clear from 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 ('compute'), resource ('hash digest'), and input ('input string'), and enumerates supported algorithms. It clearly distinguishes from siblings like verify and jwt_decode by focusing on digest generation.

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

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

Provides explicit qualifiers for sha1/md5 ('only for compatibility/checksum use cases') and directs 'anything security-relevant' to sha256. Does not explicitly name alternative tools, but gives clear conditional guidance for algorithm 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?

With no annotations provided, the description must disclose behavioral traits, but it only mentions the auth requirement ('Requires an admin owner_key') and the action. It does not state side effects (e.g., sending an email), reversibility, failure modes, or response format, which is a significant gap for a 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?

The description is a single, front-loaded sentence that states the core purpose before the requirement. There is zero wasted verbiage, and 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?

Despite the simplicity (2 params, full schema coverage), the description lacks behavioral context that the schema cannot provide, such as expected outcomes, error conditions, or whether the invitation is immediately effective. Without annotations or an output schema, an agent is left guessing at the tool's side effects, making the description incomplete for a mutating tool.

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

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

The input schema already provides 100% coverage for both parameters, including the default behavior of owner_key. The description adds no additional parameter meaning beyond restating the admin requirement, which is already in the schema. Baseline 3 is appropriate since the schema carries the detailed 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 clearly states the verb 'Invite' and the resource 'an email', with the target 'your account'. It distinguishes the tool from siblings like send_email_reply or register_client, leaving no ambiguity about what it does.

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

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

No guidance is given on when to use this tool versus alternatives, nor any exclusions or prerequisites beyond the admin owner_key. The description does not mention scenarios where another tool would be more appropriate, leaving the agent to infer usage from the purpose 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 clearly discloses that the operation is pure arithmetic, makes no network calls, and does not verify routing or reachability. This is valuable behavioral context 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?

Two sentences with no filler. The core functionality is front-loaded, and the no-network-call caveat is placed at the end for emphasis. Every word earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers the main behavior, the optional ip logic, and the key limitation. An agent has enough to call it correctly without further clarification.

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. The description adds a behavioral note about the 'ip' parameter (returns membership) but that is already implied by 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 ('CIDR math') and resource, listing the exact return values (network address, broadcast, prefix length, size, usable hosts). It also distinguishes itself from network-check siblings by noting it makes no network 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?

Provides a clear context for when to use it (CIDR calculations) and explicitly states what it does NOT do ('does not confirm the block is actually routed or reachable'), which implies an alternative tool for reachability checks. However, it does not name any sibling explicitly.

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 several important behaviors: no real mail is sent, checks are best-effort for some sources, Google Safe Browsing is skipped if the API key is missing, and the tool is owner-key-gated. It does not detail rate limits, timeouts, or failure behavior, but the disclosed behaviors are substantial and useful.

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

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

The description is a single dense paragraph that front-loads the core purpose and then lists the return values and checks. It is efficient and every sentence adds value, though the long list of checks makes it slightly dense. It could be broken into shorter sentences for readability, but it is not bloated.

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

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

For a read-only diagnostic tool with 2 parameters and no output schema, the description is quite complete: it explains the verdict scale, the evidence sources, the best-effort nature, the API-key dependency, and the owner-key gate. It doesn't describe the exact JSON structure of the response, but without an output schema, the description's list of return fields is a reasonable substitute. Minor gaps: no mention of timeouts or error conditions.

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. The description adds context about the domain parameter ('No real email is sent') and the owner_key gating, but it doesn't add syntax, format, or edge-case details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Check whether'), a clear resource ('a domain'), and the key constraint ('without sending real mail'). It also distinguishes itself from the sibling isemailreachable by focusing on domain-level reachability rather than email addresses. The verdict and evidence list further clarify 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 implies when to use this tool: when you need to assess domain reachability without sending real mail. It does not explicitly name alternatives or exclusions, but the sibling context (isemailreachable) and the phrase 'without sending real mail' provide clear context. It lacks an explicit 'use X instead when...' statement, so it doesn't earn 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 provided, the description carries full responsibility for behavioral disclosure. It explicitly states that no real mail is sent, lists all the per-check evidence including the SMTP RCPT TO probe, STARTTLS, reverse DNS, and Spamhaus ZEN, and notes that checks are best-effort. This is thorough and honest about the tool's probing nature.

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?

Although the description is long, every clause carries new information: the core no-send behavior, the return shape, the full list of evidence checks, the best-effort caveat, and the owner-key gate. It is front-loaded with the most important semantic distinction before enumerating supporting 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?

There is no output schema, so the description compensates by enumerating the return fields and the individual checks an agent can expect. It also covers the authentication requirement and the non-sending behavior, leaving little ambiguity about how to invoke or interpret this tool correctly.

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

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

Schema description coverage is 100%, and both address and owner_key are already well documented in the input schema. The description adds no additional parameter-level semantics beyond restating the no-real-mail guarantee and owner-key gating, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Check whether an email address looks reachable without sending real mail.' It then enumerates the returned verdicts and checks, making the tool's role distinct from siblings like send_email_reply and isdomainreachable 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 implies usage by emphasizing that no real mail is sent and that the tool is owner-key-gated, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. There is no direct mention of isdomainreachable for domain-only checks.

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 it delivers. It reveals that no cryptographic verification occurs, explains the security implications, and additionally documents the relative-expiry behavior when an exp claim exists. This gives the agent an accurate model of what the tool can and cannot be trusted to 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?

The description is compact and front-loaded: the core action comes first, the critical limitation is emphasized immediately after, and the extra expiry behavior is a short final sentence. Every sentence contributes meaningful information with no 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 one-parameter, no-output-schema tool, the description covers the main purpose, the key security caveat, and one notable extra behavior. It does not specify the exact shape of the returned header and payload or behavior on malformed tokens, but it is sufficient for an agent to understand what the tool does and when to reach for it.

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

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

The input schema already documents the single token parameter at 100% coverage, including the accepted format. The description does not add much parameter-specific detail beyond saying the token carries claims, so the baseline score 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 ('Decode'), a specific resource ('a JWT's header and payload'), and a clear scope ('base64url + JSON, no crypto'). It also explicitly distinguishes itself from verification by stating it does not verify the signature, which helps an agent tell it apart from sibling tools like verify and cert_inspect.

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

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

The description makes the intended use clear: decode a JWT to see what claims it carries. It also gives an explicit when-not-to-use warning ('Never treat a successful decode as validation'), which guides the agent away from using it for authentication or integrity checks. It does not name the specific alternative tool to use instead, but the exclusion is strong and actionable.

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

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

No annotations are provided, so the description carries the full burden. It discloses the core behavior: conditional write on value match and error return on mismatch. However, it does not mention atomicity, concurrency guarantees, what the success response contains, or whether the operation consumes any lock or lease. These are meaningful gaps for a CAS operation.

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

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

The entire description is one sentence that front-loads the verb and resource, then explains the conditional logic and error behavior. There is zero wasted text, and it is immediately scannable.

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 CAS operation, the description covers the essential conditional behavior but omits the success return value, the exact error characteristic, and the meaning of slug as a namespace. With no output schema and no annotations, these details would help an agent invoke the tool correctly and interpret results, but the core operation is still understandable.

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

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

Schema description coverage is only 20%, with only owner_key documented. The description clarifies the roles of expected_value and new_value in the CAS logic, but it does not explain slug or key, both of which are required and undocumented in the schema. The description partially compensates but leaves critical parameters underspecified.

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: 'Compare-and-swap a KV key'. It clearly distinguishes this from sibling kv_put by specifying the conditional behavior (only writes when expected_value matches) and the error outcome on mismatch. This is a precise, non-tautological purpose.

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

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

The description clearly conveys the intended use case: conditional updates where the caller expects a specific current value. It implies that unconditional writes should use kv_put rather than this tool, though it does not explicitly name alternatives or exclusions. The context is clear enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the full disclosure burden, but it only conveys the destructive intent of 'Delete'. It does not disclose what happens when the key does not exist, whether deletion is permanent and irreversible, what the return value is, or how owner_key affects authorization. For a data-destroying operation, this is a significant transparency gap.

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 efficient sentence with zero filler or repetition; the core action is front-loaded. It is short enough that it could have afforded more detail without becoming verbose, but as pure concision it succeeds. The under-specification is penalized in other dimensions rather than here.

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

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

Despite the low complexity of a single-key delete, the description is incomplete: there is no output schema, no annotations, two required parameters are undocumented in both the schema and the description, and behavior on missing keys or after success is unexplained. An agent invoking this tool cannot predict its effects or response from the available information.

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

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

Schema description coverage is only 33% — only owner_key is documented. The required parameters 'slug' and 'key' are bare string fields with no schema descriptions, and the tool description 'Delete a single KV key' adds no meaning to either. Since coverage is below 50% and the description fails to compensate by explaining the slug/key distinction, this falls below 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 verb and resource ('Delete a single KV key'), making the core operation unambiguous. The qualifier 'single' implicitly distinguishes it from the sibling kv_delete_prefix, though it never names that sibling explicitly. It does not fully earn a 5 because the differentiation is implicit 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?

No guidance is given on when to use this tool versus alternatives such as kv_delete_prefix, kv_put, or kv_cas. There is no mention of prerequisites (e.g., that a slug namespace is required) or conditions under which deletion would be appropriate. An agent must infer usage context entirely from the tool 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, the description carries the full burden of disclosing behavior. It states the destructive action (deleting all keys with a prefix) but omits critical details: irreversibility, permission requirements, whether the operation is atomic, or any side effects on related data. This is insufficient for a bulk deletion operation.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently conveys the core action and target. There is no redundancy or unnecessary detail, which is appropriate for a straightforward tool.

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

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

Given three parameters, no output schema, and no annotations, the description is far too sparse. It does not explain return values, error conditions, the meaning of slug, or the behavior when the prefix matches no keys. An agent cannot reliably invoke this tool correctly with the provided information.

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 only documents owner_key (33% coverage); slug and prefix have no descriptions. The description mentions 'prefix' implicitly but does not explain what slug represents, the relationship between slug and prefix, or how owner_key affects the operation. The description fails to compensate for the undocumented parameters.

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

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

The description 'Delete all KV keys starting with a prefix' is specific: it names the action (delete), the target (all KV keys with a given prefix), and clearly distinguishes itself from sibling kv_delete which targets a single key. This is unambiguous and directly states the resource scope.

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

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

No guidance is provided on when to use this tool versus alternatives like kv_delete or kv_cas. There is no mention of conditions, prerequisites, or cases where a different tool would be more appropriate. The agent is left to infer usage context.

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 provided, so description carries full burden. It states it's a read operation but doesn't disclose behavior on missing keys, response format, or any side effects. Minimal disclosure beyond the operation itself.

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 sentence, front-loaded with the action. No waste.

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

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

With two required parameters undocumented and no output schema, the description is insufficient. It doesn't explain what 'namespace' means or how slug identifies it, nor what the return value looks like beyond being a JSON value. Incomplete for an agent to call correctly without additional context.

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

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

Schema description coverage is only 33% (owner_key). The description mentions 'by key' but doesn't explain the 'slug' parameter or how it relates to the namespace. It doesn't compensate for the undocumented required parameters.

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

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

States a specific verb 'Fetch' and resource 'JSON value by key from your namespace', which distinguishes from kv_list (listing) and kv_put (writing). Clear 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?

Does not explicitly name alternatives or conditions. While sibling kv_* tools suggest context, the description alone doesn't tell an agent when to use this vs. other operations. Usage is implied but not 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 clearly covers atomicity, the absent-key edge case (treated as 0), storage as a JSON number, and the return of the new value. It does not address permissions or error conditions for non-numeric values, but the core behavior is well 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 packs in atomicity, absent-key behavior, storage format, and return value. There is no 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 description gives enough for a simple tool: operation, edge case, and return value. However, 'slug' is a required parameter that is left undefined, and with no output schema or annotations an agent may not know how to populate it or what errors might occur. This is a notable completeness 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 only 25% (only owner_key has a description). The description clarifies 'key' and 'delta' implicitly through 'increment a KV key by delta', but it never explains the required 'slug' parameter, leaving a significant gap. The description adds some value but does not compensate for the low 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?

States a specific action, 'Atomically increment a KV key by delta', identifying the resource (KV key), the operation (increment), and a key attribute (atomic). It distinguishes from sibling tools like kv_get, kv_put, and kv_cas by its unique atomic increment semantics.

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 atomic increment semantics imply a use case, but the description does not explicitly say when to choose this tool over alternatives like kv_put or kv_cas. It provides no conditionals, exclusions, or pointers to sibling tools, leaving usage guidance 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 makes clear this is a non-mutating listing operation and discloses pagination by cursor, which is useful. However, it does not clarify ordering, page-size behavior, or whether an omitted prefix returns all keys.

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 focused sentence with no filler. The key behavior and pagination mechanism are front-loaded, and every word contributes to understanding 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 tool with five parameters, no annotations, no output schema, and low schema coverage, the description is too sparse to make invocation fully reliable. It fails to clarify what slug refers to, how limit behaves, or what a paginated response 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 description coverage is only 20%, so the description must compensate for undocumented parameters. It adds meaning for prefix and cursor, but the required slug parameter is left unexplained and limit semantics are absent, leaving the agent to infer too much.

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 uses a specific verb ('List') and resource ('KV keys'), and distinguishes itself with two concrete behaviors: prefix filtering and cursor pagination. This clearly separates it from siblings such as kv_get, kv_put, and kv_delete.

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

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

The description gives clear context for when to use the tool: listing KV keys under a prefix and paginating with a cursor. It stops short of explicitly naming alternatives or exclusions, so it is good but not fully directive.

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 does not state whether writing to an existing key overwrites the value, whether there are any size limits, or what happens when the slug is invalid. It also doesn't mention the owner_key parameter or its default behavior, which is crucial for org-scoped operations.

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 wasted words, front-loading the core action. It is appropriately concise for a simple store operation, but it could have been slightly more informative about overwrite semantics without losing brevity.

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 is incomplete. It fails to clarify whether the key is overwritten, how owner_key affects behavior, or any error conditions (e.g., invalid slug). An agent might incorrectly assume it's safe to call without understanding side effects, making this insufficient for reliable 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 describes slug, value, and owner_key, covering 75% of parameters (only 'key' lacks a description). The description adds minimal extra meaning, just implying the value is JSON and the key is in a namespace, which is already implicit in the schema. Since schema coverage is high, 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 clear verb ('store'), a specific resource ('a JSON value under a key'), and scopes it to 'your namespace'. This distinguishes it from other KV tools like kv_get, kv_delete, and kv_list. However, it doesn't explicitly mention overwriting behavior or the requirement of a namespace slug, leaving a slight ambiguity in scope.

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

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

No guidance is provided on when to use this tool versus alternatives such as kv_put_ttl (for TTL), kv_cas (for conditional writes), or kv_incr (for numeric increments). The description does not mention any exclusions or prerequisites, so an agent cannot determine the appropriate tool based on the 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 must carry the behavioral burden. It does disclose the key expiry and not-found behavior, which is useful. However, it omits other behavioral traits such as whether it overwrites existing keys, atomicity, or error handling. For a mutation tool without annotations, this is partial transparency.

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 extraneous words. The key behavior (TTL expiration) is front-loaded, and the secondary sentence clarifies the semantic outcome. Efficient and well-structured.

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

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

Given no annotations, no output schema, and 5 parameters with low schema coverage, the description is incomplete. It does not cover authentication (owner_key), the role of slug, or the exact semantics of ttl_seconds beyond the name. An agent would need additional context to call this tool correctly.

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

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

Schema description coverage is only 20% (only owner_key is described). The description adds no parameter-level detail: it does not explain slug, key, value, or ttl_seconds beyond their names. It says 'JSON value' but does not clarify the format or constraints. With such low schema coverage, the description fails to compensate for the missing 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?

States a clear verb ('Store') and resource (JSON value under a key) with a specific TTL property. It explicitly mentions the TTL behavior, distinguishing it from sibling tools like kv_put (which likely lacks TTL) and kv_get (retrieval). The purpose is 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 usage when a TTL is needed but does not explicitly say 'use this instead of kv_put when you need expiration' or mention any alternatives. It provides context but lacks explicit routing guidance compared to the top example.

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. It goes beyond a generic 'List access keys' by stating the operation is metadata-only and that key material is never returned again. This is a genuinely useful safety-relevant disclosure. It does not discuss pagination or ordering, but for a simple list operation the key behavior is 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?

A single sentence that front-loads the operation and includes the most important caveat about key material without any filler. Every word earns its place.

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

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

For a list tool with no required parameters prelimit and a fully documented optional parameter, the description provides sufficient context for selection and invocation. The metadata-only warning compensates for the lack of an output schema, and the sibling tool names fill in the alternatives.

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 owner_key parameter is fully documented in the schema. The description itself adds no parameter-specific semantics beyond the account scoping, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List'), names the resource ('access keys'), and clarifies the scope ('for your account'). It also adds the crucial qualifier that only metadata is returned, which clearly distinguishes it from create_access_key, revoke_access_key, and update_access_key.

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 conveys clear context: use this when you need to list access keys for the current account. It does not explicitly name exclude create/revoke/update, but the verb and resource make the appropriate use fairly obvious. Lacks explicit when-not/alternative guidance, so not 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 provided, the description carries the full burden of behavioral disclosure. It discloses the visibility rule, the empty-list behavior (not an error), the subscription non-requirement, and the return shape similarity to `discussion_list`. It does not mention pagination or rate limits, but the disclosed behaviors are substantial and directly relevant to an agent's decision-making.

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

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

The description is a single, dense paragraph that front-loads the core purpose and then adds important behavioral caveats. It is longer than ideal but every sentence adds meaningful information: visibility rule, empty-list behavior, subscription non-requirement, and return shape. No wasted words, though it could be split into two sentences for readability.

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 no output schema, the description covers the key contextual needs: what is returned (same shape as `discussion_list`), edge cases (empty list), and access control. It does not mention pagination or sorting, which are common for list tools, but the reference to `discussion_list`'s shape provides a known anchor. Overall, it is complete enough for an agent 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 only 33% (only `owner_key` has a description). The description adds meaning for `tag` (it is the tag to filter by) and `limit` (implied by listing, though not explicit). However, it does not explain `limit` semantics or the `owner_key` default behavior beyond what the schema already says. The description adds some value but does not fully compensate for the low schema coverage.

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

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

The description states a specific verb ('List'), a resource ('deliberation threads carrying `tag`'), and a scope constraint ('that the caller can already see'). It also distinguishes itself from `discussion_list` by clarifying the visibility rule and from `list_subscribers` by noting subscription is not required. This is a clear, specific purpose that an agent can act 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?

The description explicitly explains when to use this tool: to list threads by tag with the same visibility rule as `discussion_list`. It also states when not to use it (if you need subscribers, use `list_subscribers`) and clarifies that subscription is not a prerequisite. This is explicit usage guidance with 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 provided, the description carries the behavioral disclosure burden. It explains that the call is scoped to the authenticated member's email, that the result includes every org/profile they can act as, and that the response shape matches verify. It does not explicitly confirm there are no side effects, but 'List' and the framing make the read-only nature reasonably clear.

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 core capability is front-loaded, the output shape is referenced efficiently, and the intended use case is stated in a single 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 single-optional-parameter read-style tool with no output schema, the description covers the essential context: what it lists, who it lists for, what shape the response takes, and when to reach for it. It could add a little more about failure or empty-result behavior, but nothing critical is missing for correct invocation.

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

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

The input schema already documents owner_key fully, including its optionality and Authorization header fallback. The description adds useful usage context about holding one owner_key and discovering others, but it does not need to add much because schema coverage is 100%.

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: 'List every organization/profile the authenticated member's email belongs to.' It also differentiates itself from verify by referencing the same profiles[] shape and by positioning itself as the discovery entry point when the caller already holds one owner_key.

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

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

The description explicitly states when to use the tool: to discover other orgs when the client already has one owner_key. It does not name when-not conditions or alternative tools besides referencing verify for output shape, so it falls just short of the top score.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. Beyond the word 'List' implying a read operation, it discloses no details about pagination, ordering, response shape, or any access requirements.

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. It efficiently conveys the essential purpose without redundancy.

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

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

For a low-complexity list tool with one fully documented optional parameter, the description and schema together are largely sufficient. Minor gaps remain because no output shape or behavioral expectations are mentioned, but these are minor given the tool's simplicity.

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

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

The single optional parameter owner_key is fully documented in the schema with its defaulting behavior and relationship to the Authorization header. Since schema description coverage is 100%, the description itself adds no additional parameter meaning, matching 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 uses the specific verb 'List' with the resource 'roles' and scopes it to 'defined for your account,' which clearly identifies the tool's purpose. This distinguishes it from sibling tools like create_role, update_role, and delete_role, and from list_access_keys or list_profiles.

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 what the tool does but gives no explicit guidance on when to use it versus alternatives like list_access_keys or list_profiles. There are no when-to-use criteria, exclusions, or comparisons provided.

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

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

With no annotations, the description carries the disclosure burden. It does this well: it states it 'only lists past/current registrations,' clarifies that it cannot hold open an SSE stream, and points to the raw HTTP endpoint for registration. It falls just short of describing the returned payload shape or pagination, but it provides strong behavioral context beyond simple verb-resource semantics.

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 no filler. The core purpose is front-loaded, followed immediately by sibling distinction and a critical behavioral limitation. 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 low-complexity read-only listing tool with one optional parameter, the description is complete: it covers what is listed, who it is scoped to, how it differs from the sibling, and why registration is out of scope. The absence of a return-type specification is acceptable for a list operation whose nature is clear from the 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 coverage is 100%, and the schema already fully describes owner_key including the default behavior from the Authorization header. The description's 'for your account' reinforces the parameter's scope but does not add meaningful detail 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 states a specific verb and resource: 'List SSE_hook registrations for your account.' It clearly distinguishes this tool from the sibling list_webhook_targets by describing it as the 'long-lived-outbound-stream sibling' and by specifying the subscriber context ('no stable inbound address').

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

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

The description explicitly names the alternative list_webhook_targets and gives the selection condition ('for subscribers with no stable inbound address'). It also states that registration happens over the raw HTTP POST /sse-hooks endpoint and that this MCP call cannot hold the SSE stream open, effectively telling the agent when not to use this tool.

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

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

With no annotations provided, the description carries full behavioral disclosure burden and does so exceptionally. It reveals the gating rule, the hard denial for non-subscribers, the deliberate anti-disclosure rationale, and the indistinguishable error behavior across zero/many/nonexistent tags.

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

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

The description is dense but every sentence earns its place. The core behavior is front-loaded, the gating rule is highlighted, the rationale is compactly explained, and the return payload is stated at the end without redundancy.

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

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

Given no output schema, the description still specifies the return fields: account_id, org, and subscribed_at. It also covers error semantics and authorization requirements, making the tool fully callable and interpretable by 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?

The description clarifies that `tag` is the tag whose subscribers are listed, adding meaning beyond the schema's bare `tag` string field. The optional `owner_key` parameter is already fully documented in the schema, so the description need not repeat it.

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

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

The description opens with a concrete verb-resource pair: 'List every account currently subscribed to `tag`.' This clearly identifies the tool's purpose and distinguishes it from tag-adjacent siblings like list_by_tag by specifying the exact resource being listed (subscriber accounts).

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

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

The description provides explicit call-time context: the caller must themselves be a subscriber, and non-subscribers receive a hard denial. It does not explicitly name alternative tools to use when conditions are not met, but the gating precondition is unambiguous and actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a non-obvious and important behavioral fact: secret values are never returned by this operation. The 'list' verb also implies a read-only operation, and nothing in the description contradicts the absence of mutation.

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 with no filler: the first states the operation and scope, and the second adds a high-value behavioral caveat. Every word earns its place.

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

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

For a simple optional-parameter list tool with no output schema, the description provides the operation, scope, and a critical secret-handling caveat. A more detailed return-shape description would improve it, but the low complexity makes the current description 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%, so the parameter semantics are already fully documented in the input schema. The description contributes only 'your account', which loosely aligns with the owner_key default behavior but adds no new parameter-level detail.

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, 'List', and names the resource, 'outbound webhook target registrations for your account'. This clearly distinguishes it from sibling tools like register_webhook_target and unregister_webhook_target.

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?

'For your account' establishes the intended scope, and the caveat 'Secrets are never returned again after registration' tells agents not to expect secret values and to capture them at registration time. It does not explicitly name the register/unregister siblings as alternatives, but the context is clear.

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

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

With no annotations, the description carries the full burden. It discloses that the item is permanently removed, which is a destructive behavior. However, it does not mention the need for a valid lease, idempotency, or what happens if the receipt is invalid. The core destructive nature is stated, but context is minimal.

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

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

The description is a single sentence that is front-loaded with the action and resource. It is concise, with no wasted words, and is appropriately sized for a simple acknowledgment operation.

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

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

There is no output schema, and the description does not mention return values or error conditions. It also does not state the prerequisite of having a valid lease or that the receipt comes from a prior queue_fetch or queue_pop_lease call. An agent cannot fully determine how to invoke it correctly without additional context.

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

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

Schema description coverage is 50%: the required 'receipt' parameter lacks a description, and the tool description does not explain what a receipt is or how to obtain one. The optional 'owner_key' is documented in the schema, but the description adds no semantic value beyond what is already present.

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 ('Acknowledge'), resource ('leased queue item'), and method ('by receipt, permanently removing it'). This clearly differentiates it from sibling tools like queue_nack (which would not remove) or queue_pop (which might not require a receipt).

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 guidance is provided on when to use this tool versus alternatives such as queue_nack or queue_pop_lease. The verb 'Acknowledge' hints at successful processing, but there is no mention of conditions for choosing this over others, nor 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?

With no annotations, the description carries the behavioral disclosure burden. It does disclose consumption, FIFO order, and the empty-queue null return. However, it does not say whether the item is permanently removed or leased, whether acknowledgment is required, or how errors like a missing queue are handled—gaps that matter given queue_ack, queue_nack, and queue_receipt_status siblings.

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 verb, resource, and ordering guarantee. Every sentence earns its place: one defines the action, one gives usage context and the empty-queue result. No filler or redundant restatement.

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

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

There is no output schema, so the description must explain what a successful call returns, but it only covers the empty case. It also omits the ack/nack lifecycle and whether this operation removes or leases the item. For a consuming tool with no annotations, that leaves an agent uncertain about side effects and follow-up calls.

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

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

Schema coverage is only 33%, and the description does not compensate. The required name and slug parameters have no descriptions, and while 'named queue' hints that name identifies the queue, slug is left unexplained and the relationship between name and slug is unclear. The optional owner_key is the only parameter with actual schema 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 names a specific verb (fetch/consume), a specific resource (a named queue), and an ordering guarantee (FIFO, oldest visible item). It also distinguishes itself from queue_pop by stating they behave the same and references queue_list_items, so an agent can tell this apart from sibling queue 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 concrete context: use this after queue_list_items or after finding the right queue. It names queue_pop as a same-behavior alternative but does not explain when to prefer one over the other, so the exclusion guidance is incomplete.

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 meaningful work: it discloses non-destructive behavior, FIFO ordering, returned content (item ids and values), pagination via cursor, and owner-only access. It doesn't explain visibility semantics or error behavior, but it provides substantial behavioral transparency beyond the tool name.

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 short sentences with no filler. The core behavior is front-loaded ('non-destructively, in FIFO order'), followed by useful return and pagination details, and the access constraint is stated last. 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?

There is no output schema and no annotations, so the description must be more complete. It covers purpose, ordering, pagination, and ownership, but omits the role of the required slug/name parameters, the behavior of limit, and the exact output shape beyond 'item ids and values.' An agent would need additional inference or external knowledge to call it reliably.

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

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

Schema description coverage is only 20%, so the description must compensate. It explains that cursor is for pagination and mentions owner-only access, but it does not explain the required 'slug' and 'name' parameters or the 'limit' parameter. For a tool with five parameters, this leaves most of the calling contract unexplained.

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

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

The description states a specific verb ('List') and resource ('visible items in a queue'), and adds the key qualifiers 'non-destructively' and 'in FIFO order.' This clearly distinguishes it from destructive queue tools like queue_pop and queue_ack without needing to open 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 the tool: to inspect items non-destructively and paginate with a cursor. It doesn't explicitly name alternatives like queue_pop/queue_fetch or state when not to use it, but the non-destructive framing makes the intended use obvious.

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

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

With no annotations, the description carries the full burden. It explicitly discloses the owner-only restriction and the glob pattern behavior, including the segment matching rule and empty pattern case. It implies a read-only operation but does not explicitly state side effects or return format, which is a minor gap.

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 core purpose and key behavior front-loaded. It is concise and free of redundancy, efficiently conveying the glob semantics and access restriction without extraneous detail.

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

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

For a listing tool with no output schema, it does not describe the return format, pagination, or ordering. However, it provides enough context about the pattern and access to make the tool callable. The missing details are minor for a simple list 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 only 33%, so the description must compensate. It thoroughly explains the pattern parameter with concrete examples, but it does not explain the required slug parameter, leaving its meaning ambiguous. Owner_key is covered by the schema, so the description adds value mainly for pattern.

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 and resource: 'List queue names under a namespace matching a glob pattern.' It distinguishes from sibling queue tools (e.g., queue_list_items) by focusing on queue names rather than contents, and the glob semantics further clarify its scope.

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

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

It provides explicit context on access restrictions (owner-only) and the glob matching behavior, which informs when to use this tool. However, it does not explicitly name alternatives or state when not to use it, though the unique purpose is implied by the name and description.

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 it does disclose the key mutation: the item is returned to the queue and made available to another consumer. It also implies a precondition that the item must be leased and identified by receipt. It does not discuss errors, idempotency, or auth, but the central 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?

A single efficient sentence that is front-loaded with the operation and immediately states the consequence. There is no repetition of the tool name or schema fields, and every clause 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 description is adequate for the basic call shape and schema covers owner_key, but since there is no output schema or annotations, an agent is left without guidance on return values, error conditions, or what happens if the receipt is invalid or already consumed. These gaps keep it from being fully complete.

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

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

Schema coverage is only 50% because the required receipt parameter lacks a description. The tool description helps by indicating receipt is the lease identifier, but it adds nothing about owner_key beyond the schema's own description. This is a partial compensation for the undocumented parameter.

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

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

The description uses a specific verb ('Negative-acknowledge') with a clear resource ('leased queue item') and the identifying mechanism ('by receipt'). It also explains the core effect, returning the item to the queue, which distinguishes it from positive ack and pop operations among 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 conveys clear context: use this when a leased item should be requeued for another consumer rather than permanently removed. It does not explicitly name alternatives or give when-not-to-use conditions, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses FIFO ordering, namespace scoping, and the critical behavior of returning JSON null (not an error) on empty queues. It does not cover error cases like nonexistent queues or authentication failures, but the empty-queue behavior is the most important edge case and is handled. This is adequate disclosure for a simple pop operation.

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

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

The description is two sentences, concise and front-loaded with the core action. It includes essential behavior details without fluff. Every sentence earns its place.

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

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

For a simple pop operation with no output schema, the description covers the return type (item or JSON null) and the core behavior. It could mention error handling for missing queues, but that is a minor gap given the tool's simplicity. The owner_key default is documented in the schema, so not repeating it here is acceptable. Overall, it is nearly complete for an agent 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 coverage is only 33% (only owner_key has a description). The description adds no parameter-level detail beyond 'named queue' (for name) and implies slug is an identifier, but does not explain what slug is or how it differs from name. The owner_key default behavior is in the schema, but the description does not reinforce it. Given low coverage, the description fails to compensate for the undocumented parameters.

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

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

The description clearly states the action (Pop), the target (oldest item from a named queue), and key constraints (FIFO, in your namespace). It effectively distinguishes from siblings like queue_fetch (which likely doesn't remove) and queue_pop_lease (which suggests lease semantics). The verb-resource pairing is specific and 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 to remove and return the oldest item) but does not explicitly contrast it with alternatives like queue_fetch or queue_ack. The phrase 'remove and return' signals the removal behavior, but an explicit note about alternatives would strengthen guidance. Given the queue tool family, it's fairly clear, though not exhaustive.

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 transparency burden. It discloses the non-destructive side effect, the lease movement, the exact return shape, the empty-queue null result, and the required acknowledgment lifecycle. It does not mention lease expiration or authorization requirements, but core behavioral traits are 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?

Three compact sentences front-load the core action and then provide return format, lifecycle instructions, and the empty case with no filler or redundancy. Every sentence contributes essential 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?

The description is strong on the operation, return value, empty case, and follow-up calls, which covers much of what an agent needs. However, with no annotations, no output schema, and significant parameter documentation gaps, it is not fully complete: lease timeout behavior and the meaning of slug/name/lease_seconds are left implicit.

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

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

Schema description coverage is only 25%, since only owner_key has a description. The tool description does not explain slug, name, or lease_seconds semantics, which are required parameters. The word 'lease' hints at lease_seconds, but the description does not compensate for the mostly undocumented schema.

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

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

The description specifies an exact operation ('pop the oldest visible item'), the resource ('a queue'), and the key behavioral nuance ('non-destructively', 'moving it into a lease'). It is clearly distinguishable from sibling tools like queue_pop because the lease/ack/nack lifecycle is explicit.

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 operational context: use this when you need a non-destructive pop that requires a lease, and it explicitly tells the caller to follow up with queue_ack or queue_nack. It does not name specific sibling alternatives or state when queue_pop/queue_fetch would be preferred, but the lease semantics make the intended use apparent.

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 return shape ({item_id}), the non-sensitive nature of push ('cheap/open by design'), and how to track delivery via queue_receipt_status. It does not mention side effects like queue auto-creation or idempotency, but these are minor for a push operation. The description adds meaningful behavioral context 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?

Two sentences with no fluff. The core action is front-loaded, and the follow-up usage is stated efficiently. 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 is simple, and the description explains the return value and how to use it with a sibling tool. It does not mention error conditions or queue auto-creation, but these are not critical for a push operation. The absence of an output schema is compensated by the description's mention of the returned item_id.

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 does not add extra meaning to the parameters beyond what the schema already documents. It mentions the return value but not parameter specifics, which are fully covered in the schema.

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

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

The description states a clear, specific action: 'Push a JSON value onto the tail of a named queue.' It names the resource (queue) and the direction (tail), and distinguishes it from the sensitive pop operation. It also mentions the return value, which helps the agent understand the tool's 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 provides context that push is cheap/open and contrasts with pop, implying push is the safe, immediate operation. However, it does not explicitly name alternatives like queue_push_delayed or state when to choose one over the other. It does mention a follow-up tool (queue_receipt_status), which is helpful but not an alternative selection guide.

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 behavioral burden. It discloses the key delayed-visibility behavior and the return shape. It does not mention potential edge cases or side effects, but the core mutation and timing semantics are transparent enough.

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 behavior, then use cases, then return note. Every sentence earns its place and there is no filler.

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

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

The description covers the core behavior, when to use it, and the return value, which is good for a queue mutation tool. However, with no output schema and low parameter documentation, the missing definitions of required slug and name leave an important gap for correct invocation.

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

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

Schema description coverage is only 20%: only owner_key has a schema description. The description adds meaning for value ('JSON value') and visible_after_seconds ('elapsed'), but leaves the required slug and name undefined in both the schema and the description, so an agent cannot confidently infer what those fields identify.

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 and resource: 'Push a JSON value onto a queue' with a distinctive delayed-visibility behavior. It explicitly distinguishes this from queue_push by saying the item is 'invisible to pop/pop-lease until visible_after_seconds have elapsed' and notes it returns the same shape as queue_push.

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

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

It gives explicit use cases: 'Use this for retries, backoff, or scheduled work.' This makes the intended context clear, though it does not explicitly say when not to use it or name a direct alternative beyond referencing queue_push.

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 full behavioral disclosure. It explains the return behavior across edge cases, notes that failure cases are intentionally indistinguishable, and states the owner-only constraint. It does not describe the exact non-null response shape or auth failure behavior, but it covers the key semantics.

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. Every clause adds useful information, including null semantics, indistinguishability, and ownership requirements. There is no filler or redundant restatement.

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 status lookup, the description covers purpose, return-null behavior, ownership, and cross-parameter relationships. The lack of an output schema and a few undocumented parameter descriptions keep it from being fully complete, but an agent gets enough to invoke it correctly in most cases.

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

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

Schema coverage is only 50%, and the description adds some relational context by tying item_id to slug/queue_name and explaining the null case. However, it does not define slug or name parameters, and it mostly relies on the schema for item_id and owner_key meaning. The description partially compensates but leaves gaps.

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

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

The description states a specific verb and resource: 'Read receipt for one message.' It clarifies what the receipt means ('popped/leased' vs 'ack'd') and what null indicates, which makes the tool's unique role unmistakable among queue siblings. The information-exposure rule further distinguishes it from other queue operations.

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

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

The description makes the intended use clear: check whether a message was delivered or processed, and interpret null as no receipt. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to decide when this tool applies.

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 explicitly disclaims credential granting and approval skipping, and correctly scopes the side effect to labeling the client_id used with device_start. This prevents an agent from assuming the tool performs authorization.

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

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

Three sentences deliver purpose, usage timing, and explicit non-effects with no filler. The most important outcome is front-loaded, and the limitation is stated at the end without undermining the core message.

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

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

For a single-parameter tool with no output schema, the description is complete: it explains when to call it, what it changes, what it deliberately does not change, and how it relates to the adjacent device_start flow. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-tool context by connecting client_name to the client_id used in device_start, but it does not add meaningful detail about the parameter's format, constraints, or behavior beyond what the schema already states.

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

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

The description names a specific action ('Register this MCP client'), cites the relevant standard (RFC 7591), and states the practical effect: the client name appears on the device_start approval screen. It clearly distinguishes the tool from device_start and register_webhook_target by explaining what registration does for the approval flow.

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 timing ('call this once before device_start on first setup'), states that it is optional but recommended, and clarifies what it does NOT do ('Does NOT grant any credential or skip human approval'). This tells an agent exactly when and why to invoke 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?

No annotations are present, so the description carries the full burden, and it does so thoroughly. It discloses event matching rules, dot-hierarchical prefix matching, the ownership requirement, the one-time-only return of the signing secret, and the exact HMAC signature header format for verification.

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

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

The description is dense but front-loaded: the main action comes first, followed by matching behavior, ownership, non-recoverable secret, and signature verification. Every sentence adds needed operational context, though the long first sentence includes some redundancy with the schema's parameter docs.

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

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

Given the tool's complexity and the absence of annotations and an output schema, the description is largely complete. It covers invocation semantics, authentication requirements, the one-time secret, and verification details; only edge behaviors like duplicate registrations or error cases 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 description coverage is 100%, so the baseline is 3 even without additional parameter explanation. The description does restate and slightly extend the prefix semantics by naming kv put, queue push, and topic publish as event sources, but it does not add materially new meaning beyond the schema's own parameter descriptions.

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

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

The opening phrase 'Register an outbound webhook target' names a specific verb and resource, and the description immediately specifies the triggering behavior and matching semantics. It clearly distinguishes this from sibling tools like list_webhook_targets and unregister_webhook_target.

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 the tool is appropriate: it is for registering a webhook target that will receive POSTs on matching writes, and it states the ownership prerequisite. It does not explicitly call out alternatives or when-not-to-use cases, but the purpose is evident from the 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, the description carries the full behavioral disclosure burden. It discloses that the link is emailed and not returned, but it directly conflicts with the schema's note that in the current no-SMTP setup the link may be returned. It also omits expiration, rate-limit, and idempotency behavior, so the agent receives partially misleading behavioral information.

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 tight sentence with the core action front-loaded and the important 'not returned here' caveat placed immediately. The mention of the `verify` step earns its place by providing necessary flow context 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?

This is a simple one-parameter tool, and the description covers the main flow and names the next step. However, it fails to reflect the no-SMTP return behavior mentioned in the schema and leaves out practical details like link expiration or error behavior, so the agent's understanding is incomplete.

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 email parameter is already well described, including the no-SMTP caveat. The description adds no parameter-level meaning beyond restating that the link is for that email, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource — 'Request a magic sign-in link for an email' — and clearly distinguishes this from the sibling `verify` tool by naming it as the follow-up step. An agent can tell exactly what this tool 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 gives a clear procedural context: request the link, retrieve the token from email, then pass it to `verify` to complete sign-in. It does not explicitly state when *not* to use this tool or compare it with alternatives, but the named flow is sufficient guidance for the intended 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 provided, the description carries the full disclosure burden, and it does well: it states the operation is a soft-delete, irreversible ('can never authenticate again'), preserves metadata, and requires admin-level auth. It does not mention idempotency or what happens to existing sessions/tokens, which keeps it slightly short of a 5.

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 terse sentences deliver the action, the critical identifier nuance, the side-effect model, and the auth requirement. Nothing is wasted, and the most decision-relevant fact (revoke by id) is front-loaded.

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

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

For a mutating tool with no output schema and no annotations, the description covers the essential context: what is revoked, how it is identified, what the long-term effect is, and what auth is needed. Missing are error cases and idempotency, but an agent can safely invoke this tool from the given information.

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 thoroughly. The description adds the 'admin' requirement for owner_key and re-emphasizes that id is not the raw key material, but these largely paraphrase what the schema already states. This matches 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 names a specific verb and resource ('Revoke an access_key by its id') and clarifies the identifier type ('not the raw ak_... key material'), which sharply distinguishes the action from create/update/list siblings. It does not explicitly name sibling tools, but the action is clear and 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 states a prerequisite ('Requires an admin owner_key') and hints at the soft-delete trade-off (metadata stays queryable), which implies when to choose this over a hard delete. However, it never explicitly states when to use this tool versus alternatives, nor does it name any sibling like update_access_key or list_access_keys.

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 does well: it discloses the lookup by message_id, the from-address construction, and the key side effect that the reply is queued for delivery rather than sent synchronously. It also clarifies the security model: any valid owner_key works and the gate is anti-abuse, not ownership enforcement. It does not mention failure modes or rate limits, but the core 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?

Three tightly written sentences with no filler. The first sentence states the action, the second describes the mechanism and side effect, and the third gives the auth requirement—each sentence earns its place and the most important information is front-loaded.

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

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

For a three-parameter tool with no annotations or output schema, the description explains the required inputs, the sender, the queueing side effect, and the auth requirement. The only notable omission is what the caller should expect back on success, but since no output schema is declared, this is a minor gap rather than a blocking 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 description coverage is 100%, and each parameter has a specific description already. The tool description adds contextual behavior (lookup by message_id, reply construction) but not much parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Reply to an inbound email stored by the mailbox ingest endpoint.' It also names the lookup key (message_id) and the sender address construction, making the tool's function unambiguous. No sibling tool competes for this exact email-reply 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 clearly frames when to use it: when replying to an inbound email that came through the mailbox ingest endpoint. It provides the auth-related context ('Requires any valid owner_key') and the gating semantics, but does not explicitly name exclusions or alternative tools, though no obvious email-send sibling exists among the list.

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 itself must disclose behavior. It usefully notes that 'credit balance is null until that subsystem ships' and scopes queue depth to today, but it does not state auth requirements, return shape, or whether results are approximate, leaving some burden unmet.

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 front-loaded sentence delivers the core capability then the important caveat, with no 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?

For a low-complexity tool with one optional parameter and no output schema, the description tells the agent what counts it will get and flags a known null field. The only notable omission is a more precise statement of the return format, but the listed counts largely cover 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 coverage is 100% and the single optional owner_key parameter is already documented in the schema. 'For your org' lightly reinforces that the parameter scopes results, but the description adds no new parameter-level meaning beyond the schema.

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

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

The description names a specific verb and resource ('Get counts for your org') and enumerates exactly what is included (KV item count, queue depth today). This distinguishes it from sibling tools like kv_list and queue_list_names, which inspect individual items rather than org-wide aggregates.

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 use is clear: use it when you need org-level aggregate counts. However, it never explicitly says when to avoid it or names alternatives, so an agent must infer that kv_list or queue_list_names are the more detailed 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 fully carries behavioral disclosure. It reveals account-level sharing, idempotency, the lack of effect on visibility, and the exact two grants (being listed and being allowed to call list_subscribers, which hard-denies non-subscribers). It also notes the tag validation constraints. This is exhaustive transparency for a mutation.

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

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

Every sentence adds essential information. The key distinction (account-level vs per-thread) is front-loaded, followed by idempotency, non-effects, and grants. No filler or redundancy; the length is justified by the complexity of the behavior it must convey.

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 subscribe action with subtle implications, the description covers all necessary aspects: what subscribing does, what it doesn't do, idempotency, and interaction with list_subscribers. It also details parameter constraints. No output schema is needed for a void operation, and the description is 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?

The schema covers 100% of parameters (tag and owner_key) with detailed descriptions. The tool description repeats the tag format and does not add new parameter-specific meaning beyond what the schema already provides. Baseline 3 applies because the schema does the heavy lifting; the description adds context about account-level state but not parameter 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 clearly states the action: 'Subscribe the caller's account to a tag', with a specific verb and resource. It distinguishes itself from siblings like unsubscribe_tag and list_subscribers by explicitly stating what it does not do (does not change thread visibility) and what it grants (inclusion in subscriber lists and access to list_subscribers).

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 effects and side conditions: it is idempotent, account-level, and grants specific capabilities. It implicitly routes to the correct usage (e.g., to become a subscriber or to call list_subscribers) but does not explicitly contrast with alternative tools like unsubscribe_tag. The context is clear enough for an agent to decide when 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 provided, the description carries the safety burden. It does reveal the precondition (valid owner_key for the same email), the output (a fresh owner_key), and that no fresh browser login is required. However, it is silent on whether an existing owner_key remains valid after minting, what happens when the account_id does not match, or any broader security side effects of minting a new credential.

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 with a distinct job: precondition/action, constraint, and usage guidance. The most important action is front-loaded and there is no filler or redundancy.

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

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

For a two-parameter tool with complete schema descriptions and no output schema, the description covers the necessary call semantics and even indicates the return value ('fresh owner_key'). It does not describe the return format or key lifecycle, but given the low complexity these are minor 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?

The schema already provides full descriptions for both parameters, including the optional owner_key defaulting from the Authorization header and the account_id requirement. The tool description adds no meaningful semantic detail beyond restating the same-email constraint, so the high schema coverage baseline of 3 is appropriate.

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

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

The description states the exact action ('mint and return a fresh owner_key') and the target ('requested account_id'), plus the binding constraint that the account must belong to the same email. This makes the tool's function unambiguous and clearly distinct from the sibling tools, none of which perform credential minting for an organization.

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

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

The description explicitly frames the use case: 'save additional org credentials locally without requiring a fresh browser login.' It gives a clear context for when to use the tool, though it does not mention when-not-to-use or point to a specific 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. It discloses that the code is short-lived and one-time, and explains the downstream effect on message routing. However, it does not mention failure modes, expiration handling, revocation, or whether the operation requires specific permissions beyond the owner_key. This is a moderate disclosure but not exhaustive.

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

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

The description is two sentences with no wasted words. The first sentence states the action and primary purpose, the second clarifies the effect on inbound messages. It is front-loaded and directly useful.

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 optional parameter and no output schema, the description explains the purpose and usage well. However, it does not specify the return format or indicate that the response contains the code, which an agent would need to know to complete the pairing flow. This is a notable gap given no output schema is provided.

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 owner_key is already documented in the schema, including its default behavior. The description adds no additional meaning about the parameter itself, so it meets the baseline without exceeding it.

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

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

The description states a specific action ('mint a short-lived one-time pairing code') and its purpose: linking a Telegram chat to the user's account, with the effect that inbound messages land on the telegram.inbound queue. It clearly distinguishes itself from sibling tools like telegram_send or device_claim by specifying the pairing flow.

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 usage instructions: DM the code or send /start <code> to the bot, and explains the consequence (inbound messages go to the namespace queue). It does not explicitly contrast with alternative tools or list when not to use it, but the context is sufficiently clear for an agent to select it when a Telegram pairing 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?

With no annotations, the description carries the full burden. It discloses a notable behavioral trait: error obfuscation (same error for both failure cases). However, it omits other details like success behavior, response format, or any side effects. Given the simplicity, this is adequate but not rich.

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 purpose, no fluff or repetition. Efficient and directly to the point.

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 send operation with no output schema and no annotations, the description covers the essential prerequisite (pairing) and a critical edge case (error obfuscation). It doesn't mention success return values, but that's likely obvious. Slightly incomplete on error handling details (e.g., rate limits, message size), but overall sufficient for an agent to use 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 67%, with chat_id and owner_key well described in the schema. The description adds no new parameter-specific information beyond the pairing mention, which is already in chat_id's schema description. It doesn't clarify the 'text' parameter, but that's self-evident. Thus it adds minimal value beyond the schema.

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

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

The description clearly states the action (send text message), the resource (Telegram chat_id), and the condition (must be paired). It also implicitly distinguishes from the sibling telegram_pair_code by focusing on sending after pairing. This is specific and 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 usage after pairing, mentioning the pairing code tool. It also warns that sending to unpaired or foreign chat_ids is rejected, effectively saying 'do not use this until paired'. However, it doesn't explicitly name alternatives beyond the pairing requirement, but for this tool the main alternative is telegram_pair_code, which is implicitly referenced.

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 discloses the return shape ({ok, cursor}) and the multi-reader tailing behavior, which is helpful. However, it omits side effects, durability, ordering, permissions, or any error semantics, leaving the agent to infer the mutation nature from the word 'Publish'.

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

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

Two sentences, no wasted words. The core purpose and the most important behavioral detail (cursor tailing) are front-loaded. 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?

Given the absence of annotations and output schema, the description covers the return value and the tailing pattern, which is useful. But the ambiguous parameters and lack of usage guidance mean an agent would likely need to probe or ask for clarification before a correct 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?

The schema covers only 1 of 4 parameters (owner_key). The description adds minimal compensation by calling the event 'JSON', but it does not explain 'slug' or 'name'. An agent cannot reliably determine what constitutes a topic or how to identify it without further context.

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

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

The description clearly states the action ('Publish') and the resource ('a topic'), with specificity about the payload ('JSON event') and the return value. It is immediately distinguishable from siblings like topic_read or queue_push.

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

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

The description implies the tool is for publishing events that can be tailed by multiple readers, but it never explicitly says when to use this over comparable tools (e.g., queue_push, discussion_post). There is no when-not guidance or named 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 burden of behavioral disclosure. It discloses the return format explicitly ({events: [{cursor, event}], next_cursor}) and explains cursor default behavior. It implies a read-only operation via the word 'read' but does not explicitly confirm non-mutability or mention any other side effects, which is a minor gap.

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

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

The description is two sentences with no filler. It front-loads the core action and then adds the key cursor behavior and return format. 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 5 parameters, no output schema, and no annotations. The description explains the return shape and cursor, but omits essential information about required parameters (slug, name) and the 'limit' parameter. An agent would be uncertain how to correctly identify the topic or constrain results, making the description incomplete 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 only 20%, so the description must compensate. It adds meaning only for the 'cursor' parameter (omit or 0 to start from beginning). It does not explain 'slug', 'name', or 'limit', which are otherwise undocumented in the schema. This leaves critical parameters ambiguous.

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 'read' and the resource 'events from a topic', and specifies cursor-based semantics. It distinguishes itself from sibling tools like topic_publish and queue_fetch by focusing on reading events with a cursor mechanism.

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 context on how to start from the beginning (omit cursor or pass 0), but does not explicitly state when to use this tool versus other read-oriented siblings like queue_fetch or discussion_list. No exclusions or alternative routing is provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it explicitly states the destructive side effects — dropping any currently-open connection, removing the row, and stopping pushes after the call. Minor gap: it does not disclose behavior for an unknown/expired id (error vs. silent no-op).

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

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

Two sentences with zero filler: the first front-loads the action and id source, the second packs in all consequential side effects. 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 2-parameter tool with no output schema and no annotations, the description covers the action, id provenance, destructive side effects, and post-call condition. The only notable omission is the return value or error semantics, but the core information an agent needs to invoke 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 coverage is 100%, so the baseline is 3. The description's mention of the id's provenance mirrors the schema's own description of the 'registered' event and list_sse_hooks, adding no new meaning beyond the structured field. The owner_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.