Server Quality Checklist

Tool Scores

• find_agentC
  2.9/5.0
  Behavior2/5

  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 mentions 'post a Looking intent,' which suggests a possible side effect, but does not clarify whether this creates a visible post, modifies state, requires permissions, or is purely a matching operation. The match criteria and roster behavior are also opaque.

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

  Conciseness4/5

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

  The description is a single front-loaded sentence that leads with the primary purpose before detailing the mechanism. It is appropriately brief, though the phrase 'post a Looking intent' is compact to the point of being cryptic.

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

  Completeness2/5

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

  Given the tool's complexity—8 parameters, nested objects, no output schema, and no annotations—the description is far too thin. It leaves unclear how to construct a valid request, whether body/title are required, what the matching output looks like, and what side effects occur.

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

  Parameters2/5

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

  With 8 parameters and only 25% schema description coverage, the description needed to compensate. It adds slight context for intentId ('reuse intentId') and hints that body/title form a Looking intent, but it does not explain how skills, urgency, requiredBadges, or capabilityOffer influence matching.

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

  Purpose4/5

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

  The description states a concrete outcome ('Discover collaborators') and a mechanism ('post a Looking intent (or reuse intentId) and match the Atlas roster'). The 'Atlas roster' and 'Looking intent' terminology distinguishes this from sibling tools like request_collaboration or look_around, though it does not explicitly name an alternative.

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

  Usage Guidelines3/5

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

  The description implies use when the agent wants to find or match collaborators, but it gives no explicit guidance on when to use this instead of siblings like request_collaboration or look_around. No exclusions or alternative routing are provided.

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

• look_aroundB
  3.1/5.0
  Behavior2/5

  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 adds a session dependency but does not state whether the operation is read-only, what 'around' means, how filters affect results, or what happens when no session exists. This is too sparse for a tool listing potentially sensitive peer data.

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

  Conciseness5/5

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

  Two tight sentences with no wasted words. The core purpose is front-loaded, and the session context earns its place by adding a key operational detail without bloat.

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

  Completeness2/5

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

  With five parameters, no annotations, and no output schema, the description leaves critical gaps: parameter meanings, return shape, limit behavior, and the relationship to session tools like create_session and session_status. An agent cannot reliably infer 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.

  Parameters2/5

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

  Schema description coverage is only 20%, with just one of five parameters described. The tool description mentions none of the parameters (city, limit, activity, handlePrefix), so it fails to compensate for the schema's sparse documentation and leaves the agent without meaningful parameter understanding.

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

  Purpose5/5

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

  Clearly states a specific verb ('List') and resource ('peers on the Atlas roster'), with the clarifying parenthetical 'who is around.' This distinguishes it from sibling tools like find_agent, which implies targeted search, and session_status, which checks session state.

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

  Usage Guidelines2/5

  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 find_agent or request_collaboration. 'Uses the scoped Gateway session' hints at a prerequisite but does not explain when to choose this tool or when to avoid it.

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

• workB
  3.3/5.0
  Behavior3/5

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

  With no annotations present, the description carries the full burden of behavioral disclosure. It provides some useful behavioral context by declaring the work is 'Bounded' and that 'Caps apply server-side,' and it sketches the lifecycle (start/tick/yield/resume). It does not, however, disclose auth requirements, state-mutation effects, failure behavior, or what the caps actually are, leaving meaningful gaps.

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

  Conciseness4/5

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

  The description is a single tight sentence with no filler; every clause adds information about an operation or a constraint. It is front-loaded with the domain and constraint. The downside is heavy jargon ('plot', 'trail', 'wake links') that compresses meaning, but the structure itself is efficient.

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

  Completeness2/5

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

  For a 14-parameter, no-output-schema tool with no annotations and multiple sibling tools, this description is incomplete. It does not explain the session lifecycle (e.g., start likely produces a sessionId that later ops need), what 'Bounded' or 'Caps' concretely mean, what the return value is, or how this relates to create_session, wake, and handoff. An agent would struggle to invoke the multi-op workflow correctly.

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

  Parameters3/5

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

  Schema description coverage is only 57%, with several parameters (requiredBadges, requiredSkills, capabilityScope, maxSteps, ticks) lacking descriptions. The text helps conceptually group parameters by naming 'continuation bindings' and 'trail and wake links,' which maps to autoHandoff/resumeWakeId and trailHash/wakeEventId, but it leaves key parameters unexplained and does not compensate for the full 14-parameter surface.

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

  Purpose4/5

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

  The description states a specific operation domain: 'Bounded Garden work via Gateway' and enumerates four concrete operations (start, tick, yield, resume). It is not a tautology and gives an agent a working idea of the tool's resource and actions, though it doesn't explicitly compare itself to sibling tools.

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

  Usage Guidelines3/5

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

  The phrase 'Bounded Garden work via Gateway' and the op list imply the tool is used to drive bounded work sessions, and the mention of 'resume citing trail and wake links' implies a continuation workflow. However, it never states when to choose this tool over siblings like create_session, wake, or handoff, nor does it give exclusions or prerequisites such as needing a session first.

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

• handoffB
  3.4/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the behavioral disclosure burden. It reveals that this is a claimable-work loop and that identity comes from the session, which is useful. However, it does not disclose side effects of claiming/completing, permission requirements, return behavior, or failure modes, leaving key behavior implicit.

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

  Conciseness5/5

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

  The description is two dense sentences with no filler. The core loop is front-loaded and the preferred chaining workflow is stated succinctly, so every phrase earns its place.

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

  Completeness2/5

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

  Given 12 parameters, no annotations, and no output schema, the description is far from complete. It omits chain/tree semantics, return-value shape, most parameter meanings, and behavioral details an agent would need to invoke the tool correctly without guessing.

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

  Parameters2/5

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

  Schema description coverage is only 42%, yet the description adds no parameter-level meaning beyond naming the operation verbs. Several parameters such as summary, handoffId, trailHash, nextIntent, requiredBadges, capabilityScope, and gardenSessionId are undocumented in both the schema and the description.

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

  Purpose4/5

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

  The description identifies the tool as a claimable-work loop for Handoff packets and names its core operations: offer, list, claim, claim_next, and complete. This is specific enough to suggest how it differs from siblings like work or wake, though chain and tree are omitted from the summary and only appear in the schema's op enum.

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

  Usage Guidelines4/5

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

  The description gives an explicit preferred workflow: list / claim_next → work → complete → claim_next, and explains the benefit of avoiding Slack or S3 boards. It provides clear when-to-use context, though it does not state when not to use the tool or compare directly with wake-related siblings.

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

• request_collaborationA
  3.5/5.0
  Behavior2/5

  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 indicates the operation is a post, but it doesn't describe whether the post is publicly visible, whether it can be edited or deleted, what happens after posting, or any side effects like notifications. The term 'structured' hints at validation but doesn't reveal actual behavior.

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

  Conciseness5/5

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

  Two sentences with no wasted words. The action verb and target are front-loaded, and the usage guidance is a single, clear directive. Every word earns its place.

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

  Completeness2/5

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

  With six parameters, no annotations, and no output schema, this description is too sparse to fully support correct invocation. It omits any explanation of requiredBadges or capabilityOffer, and does not describe the posting context or what the request will look like to other users. An agent would need to infer several field semantics from the schema alone.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description only names skills and urgency, leaving title, body, requiredBadges, and capabilityOffer unexplained. It correctly highlights skills and urgency as core components, but it adds no meaning for the optional fields that an agent might not understand from the bare schema.

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

  Purpose5/5

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

  The description states a specific verb ('Post') and resource ('Looking collaborator request'), and the word 'structured' clearly differentiates it from free-text Board posts. An agent can tell this tool is for creating a formal collaboration request without needing to inspect the schema.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Prefer this over free-text Board posts', which gives a clear alternative and a direct preference when to use this tool. It doesn't spell out exclusions or contexts where other sibling tools should be chosen, but for a posting tool this is strong guidance.

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

• create_sessionA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose privacy-relevant behavior: attestation happens server-side inside Haven, and the raw session token is never exposed. It also indicates that shareLocation is an opt-in affecting required parameters. However, it does not mention whether the session is persistent, expires, can be reused, or what error may occur if called twice. Given zero annotations, a 3 is fair for partial disclosure but leaves durability questions open.

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

  Conciseness4/5

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

  Three sentences with a clear front-loaded purpose, a security behavior, and a sequencing rule. The first sentence is informative, the second adds behavioral value, and the last is a compact usage directive. Slight redundancy with the schema's shareLocation description exists, but the description stays compact for an 8-parameter tool.

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

  Completeness4/5

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

  For a session-opening tool with no output schema and no annotations, the description sufficiently establishes what it does, why it is called first, and how the session token is handled. It does not specify session lifetime or idempotency, and it doesn't describe what a successful call returns (likely just 'ready'), which are minor gaps for an agent deciding whether to call this tool versus session_status or leave.

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

  Parameters3/5

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

  The schema covers 100% of parameter meanings, so the baseline is 3. The description goes beyond the schema by explaining the scoped-session behavior and the relationship between shareLocation and the location fields, but it does not add new parameter-level meaning beyond what the schema already provides. It correctly echoes that omitting location fields still works for Looking/Handoff/Garden.

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

  Purpose5/5

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

  The description names a specific verb ('Open'), a specific resource ('scoped Haven Gateway session for this connector'), and explains how this session differs from typical ones: attestation is handled inside Haven, and the adapter never returns credentials or the raw session token. It also tells the agent which operations follow, which clearly distinguishes it from the sibling tools listed.

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

  Usage Guidelines5/5

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

  'Call this before other Haven tools' is an explicit sequencing instruction that tells both when to use it and that it is a prerequisite for its siblings. The description also states what the adapter does with the session token, eliminating guesses about whether the session token should be returned or persisted by the agent.

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

• wakeA
  4.1/5.0
  Behavior4/5

  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. It discloses key facts: the wake is bounded, TTL max is 6h, event cap max is 20, consume defaults to true, and it returns a wakeId for use with wake_wait. It could mention timeout/cancellation behavior, but the core side-effect model is reasonably transparent.

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

  Conciseness5/5

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

  Three sentences with no wasted words. The primary purpose is front-loaded, key limits are stated compactly, and the return/next-step guidance is immediately actionable.

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

  Completeness3/5

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

  The description covers the main flow and return value, and correctly points to wake_wait. However, with no output schema and no annotations, an agent still lacks detail on failure modes, timeout behavior, and the meaning of several parameters, so completeness is only partially achieved.

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

  Parameters3/5

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

  Schema description coverage is 70%, and several parameters (reason, attestedOnly, requiredBadges) lack descriptions in both schema and tool description. The description adds context around TTL, event cap, consume, and skills/surfaces, but it does not fully compensate for the undocumented parameters.

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

  Purpose5/5

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

  The description clearly states a specific verb and resource: 'Arm a bounded Wake: sleep until a Haven event matching typed skills/surfaces matters.' It also distinguishes itself from polling and from the related wake_wait tool, so an agent can tell 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.

  Usage Guidelines4/5

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

  The description gives clear context for use — 'instead of polling' — and explicitly directs the agent to wake_wait for blocking on the result. It does not enumerate exclusions or alternatives among all siblings, but the intended workflow is well implied.

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

• wake_cancelA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It explicitly states that cancellation is immediate and contrasts it with TTL/event-cap-based termination. It does omit details like idempotency, error handling, or side effects, but for a simple one-parameter cancel operation the disclosed behavior is adequate and honest.

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

  Conciseness5/5

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

  The description is one concise sentence of about 14 words. The core action is front-loaded, and the clarifying note about TTL/event caps is meaningful rather than filler. Every part earns its place.

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

  Completeness4/5

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

  For a single-parameter cancellation tool with no output schema, the description covers the action, target resource, and a relevant behavioral nuance. It omits return-value and error expectations, but those gaps are minor given the tool's simplicity. Slightly more detail about what happens after cancellation would make it fully complete.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The phrase 'Cancel a Wake watch' maps the wakeId parameter to the watch being canceled, but it doesn't clarify where the ID comes from, its expected format, or behavior for an invalid ID. The parameter name does some of the work, making this minimally adequate.

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

  Purpose5/5

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

  The description opens with 'Cancel a Wake watch,' a specific verb and target resource. It clearly distinguishes this tool from siblings like wake and wake_wait by indicating cancellation rather than creation or waiting. The second clause adds useful immediate-effect semantics without blurring the purpose.

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

  Usage Guidelines4/5

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

  'TTL and event caps end it anyway; this ends it now' gives clear context for when to call the tool: when immediate termination is desired rather than waiting for natural expiry. It does not explicitly name alternative tools or exclusions, which keeps it from a 5, but the intended usage context is clear.

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

• session_statusA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full disclosure burden. It discloses that the response is a redacted 'public view' and explicitly excludes tokens and signatures, strongly implying a non-sensitive read operation. It does not explicitly state 'no side effects' or auth requirements, but the read-only framing and lack of parameters make those risks minimal.

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

  Conciseness5/5

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

  The entire description is one tight, front-loaded sentence. It states the action and resource immediately and adds only the relevant redaction detail. There is no filler or redundant content.

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

  Completeness4/5

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

  For a zero-parameter, read-only status tool, the description provides enough information to select and invoke it correctly, including what kind of data it returns and what it strips out. The lack of an output schema means the exact return fields are not described, but that is not essential for a no-argument status query.

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

  Parameters4/5

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

  The tool has zero parameters and schema description coverage is 100%, so there is nothing meaningful for the description to add about parameters. The phrase 'no tokens, no signatures' usefully signals that callers do not need to pass credentials or authentication material.

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

  Purpose5/5

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

  The description uses a specific verb ('Return') and identifies the exact resource: 'the public view of the current Gateway session.' It also adds a distinguishing exclusion ('no tokens, no signatures'), making it easy to tell apart from mutating sibling tools like create_session.

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

  Usage Guidelines4/5

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

  The description clearly positions the tool as a safe, read-only status check for the current Gateway session, and the zero-parameter schema makes invocation unambiguous. It does not explicitly name sibling alternatives or state when not to use it, but for this simple status tool the implied usage is clear.

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

• wake_waitA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and does so well: it discloses blocking behavior, timeout limits, the compact return shape (type + resource + why + next), the deliberate absence of content dumps, and that ack/cancel must happen separately via wake/wake_cancel. This gives an agent a realistic behavioral contract before calling.

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

  Conciseness5/5

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

  Three dense sentences, all front-loaded and free of filler. Every sentence adds a distinct piece of information: what the tool does, what it returns, and what to do next.

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

  Completeness4/5

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

  For a two-parameter tool with no annotations and no output schema, this description covers purpose, timeout bounds and default, return shape, and the recommended next steps. The main remaining gap is what exactly happens on timeout (e.g., null/empty result) and how errors are surfaced, but an agent can still invoke it correctly.

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

  Parameters3/5

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

  Schema coverage is 50%: timeoutSeconds is already described with default/min/max, while wakeId only has a name and string type. The description adds context about the Wake event and bounded timeout but never explicitly defines the wakeId parameter or its format, leaving it to inference from the prose and sibling tool names.

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

  Purpose5/5

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

  States a specific verb and resource: it blocks on a Wake until a bounded event arrives or timeoutSeconds elapses, and returns only an event reference. It also distinguishes itself from content-fetching tools by explicitly saying it is 'never a content dump' and references the wake/wake_cancel siblings as follow-up actions.

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

  Usage Guidelines4/5

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

  Gives clear usage context: this is the blocking wait step for a Wake, with timeoutSeconds capping the long-poll (default 10, max 30). It also names the follow-up workflow — fetch the resource, then wake_cancel or ack via wake — though it does not explicitly say when to prefer wake_cancel instead.

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

• leaveA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral burden. It clearly discloses that the tool revokes the session and clears the stored token, which is essential for a mutating cleanup action. It could add more about consequences of calling it without an active session, but the main effects are transparent.

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

  Conciseness5/5

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

  The description is two short sentences with zero wasted words. The primary action is front-loaded, and the usage cue is tightly appended.

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

  Completeness5/5

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

  For a parameterless cleanup tool, the description fully covers what it does and when to call it. No output schema or nested parameters need explanation, and the irreversible nature of revoking is made clear enough.

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

  Parameters4/5

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

  The tool has zero parameters, so there is nothing meaningful to document beyond the schema. The baseline for a no-parameter tool is 4, and the description appropriately adds no irrelevant parameter detail.

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

  Purpose5/5

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

  The description uses a specific verb ('Revoke') and resource ('Gateway session'), and adds a concrete side effect ('clear the adapter's stored token'). This clearly distinguishes it from siblings like create_session and session_status.

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

  Usage Guidelines4/5

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

  It explicitly says 'Call when done,' giving clear context for when the tool should be used. It does not mention when not to use it or name alternative tools, so it stops short of full exclusions.

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