Server Quality Checklist

Tool Scores

• handshake_logC
  2.6/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden, but it only states what the log contains and that it is recent. It does not disclose whether the operation is read-only, how the session filter behaves, whether results are paginated or ordered, or any authentication expectations.

  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 compact single line that front-loads the purpose and contains no redundant words. However, its brevity contributes to the lack of parameter and usage details.

  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 no annotations, no output schema, and 0% parameter description coverage, the description is too sparse for safe invocation. It doesn't explain the required 'session' parameter, the meaning of 'limit', or what the returned log looks like.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description adds no meaning for the two parameters. Neither 'session' nor 'limit' is explained, leaving the agent without a way to know what values are valid or what each parameter controls.

  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 clearly identifies the tool as an access log for credential reads and specifies the content dimensions (who, which credential, when, from where). This distinguishes it from sibling tools like handshake_list and handshake_get, though it lacks an explicit action verb such as 'list' or 'retrieve'.

  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?

  There is no guidance about when to use handshake_log instead of siblings like handshake_status, handshake_list, handshake_get, or handshake_put. No contexts, exclusions, or prerequisites are mentioned, so the agent must guess the appropriate scenario.

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

• handshake_putB
  3.2/5.0
  Behavior2/5

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

  No annotations are present, so the description carries the full burden of behavioral disclosure. It mentions the session-token requirement and that the operation can create or update, but does not explain overwrite semantics, permissions, return value, or idempotency.

  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?

  Two sentences with no wasted words; the key auth requirement is front-loaded and the operation is described clearly. Might be slightly richer with more behavior detail, but the prose itself is well-structured.

  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?

  This is a 5-parameter write operation with no annotations, no output schema, and 0% schema coverage, so the description needs to carry more weight. It omits return behavior, overwrite semantics, and parameter details, leaving an agent under-informed for reliable invocation in varied cases.

  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 hints at session/name/value ('credential', 'session token'), leaving note and category unexplained. The parameter names are somewhat self-evident, but the description does not compensate for the missing schema documentation.

  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 ('Store or update') with a clear object ('one credential'), making the operation's purpose unmistakable. This clearly distinguishes it from the sibling read/list/status/log 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 'Store or update one credential' implies a write operation distinct from handshake_list/get/log, but there is no explicit guidance on when to use this tool versus alternatives. No exclusions or scenarios are mentioned.

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

• handshake_listA
  3.8/5.0
  Behavior3/5

  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 does disclose that values are never returned and that an open session is required, which is useful. It does not address side effects, failure behavior, or whether the operation is strictly read-only, though 'List' strongly implies a read operation.

  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?

  A single sentence that front-loads the core purpose ('List the NAMES of stored credentials') and immediately warns about the critical limitation ('never values'), followed by the required precondition. No wasted words.

  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 simple one-parameter list operation, the description conveys the return content (names only), the security boundary (no values), and the invocation precondition (open session token). It could be improved by describing the error case for an invalid or expired session, but the tool is otherwise adequately specified.

  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 100% and the only parameter, session, is already documented as 'token from `handshake unlock`'. The description adds the nuance that the session must be open, but otherwise does not meaningfully extend the schema's parameter documentation.

  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 ('List') and resource ('stored credentials'), and clarifies the scope to names only, explicitly excluding values. This distinguishes it from sibling tools like handshake_get, which likely retrieves credential values.

  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 gives a clear precondition ('Requires an open session token') and the 'never values' caveat implies that value retrieval belongs to another tool. However, it does not explicitly name alternatives such as handshake_get or state when this tool is preferred over handshake_status or handshake_log.

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

• handshake_getA
  4.3/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 burden of behavioral disclosure. It discloses a critical non-obvious behavior: every read is written to an append-only audit log with the reason, and warns users to pass a truthful reason. This goes well beyond a simple 'read' and reveals the side-effectful nature of the operation.

  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 sentences with no wasted words. The core action is front-loaded ('Read ONE credential by name'), followed immediately by the prerequisite and the behavioral caveat. Every clause earns its place.

  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 simple read-by-name tool with three required parameters and no output schema, the description covers the essential contextual basis: what it does, the session prerequisite, the audit-log side effect, and how to supply the reason. Combined with the schema's parameter descriptions, an agent has enough information to invoke this tool correctly.

  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?

  Schema coverage is 67%: name and reason are described in the schema, but session is not. The description adds important semantics by stating it 'Requires an open session token' and re-emphasizing that the reason is recorded permanently. This compensates for the schema gap on session and reinforces the meaning of reason.

  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 and resource: 'Read ONE credential by name.' The emphasis on 'ONE' clearly distinguishes this from handshake_list, which would be the sibling for reading multiple credentials. This makes the tool's purpose unambiguous.

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

  Usage Guidelines3/5

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

  The description gives clear context for using the tool: read a single named credential, requiring an open session token and a truthful reason because of audit logging. However, it does not explicitly state when not to use this tool or name alternatives like handshake_list for enumeration, leaving some routing to inference.

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

• handshake_statusA
  4.4/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 burden of behavioral disclosure. It conveys that this is a read-only session check, requires no token, and reports session liveness, remaining time, and secret count. It does not cover exact response formatting or error cases, but it is sufficient for a zero-input status tool.

  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, information-dense sentences. The opening question immediately conveys intent, and the second sentence provides output details, auth requirements, and usage ordering without wasted words.

  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 tool with no parameters, no output schema, and low complexity, the description explains what the tool returns, that it needs no token, and when to call it. It is largely complete, though it could slightly clarify the format or units of 'how long is left.'

  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 no parameters, so the schema is trivially complete. The description adds relevant context by stating that no token is needed, reinforcing that no input is required. This meets the baseline for zero-parameter tools.

  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 the tool's purpose: checking whether the vault/session is live, with time remaining and secret count. It distinguishes itself from sibling data-access tools by being a status-only check and by saying to call it first when a credential is needed.

  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 explicit situational guidance: 'Needs no token — call this first when a credential is needed.' This tells the agent when to invoke it and establishes ordering relative to credential access, though it does not explicitly name alternative tools or when not to use it.

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