Server Quality Checklist

Tool Scores

• list_transactionsB
  3.1/5.0
  Behavior3/5

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

  The readOnlyHint annotation covers the read-only nature, and the description adds pagination and filtering behavior. However, the description says 'current workspace' while the schema includes a workspace_id parameter, potentially misleading agents about the ability to override the workspace.

  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 concise sentence with no wasted words. It front-loads the core purpose and then specifies pagination and optional filtering. However, it omits a parameter (workspace_id) that is present in the schema, slightly reducing completeness.

  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?

  The description is incomplete for a tool with four parameters, especially since workspace_id is not mentioned and the description implies a fixed scope ('current workspace'). The tool's behavior around workspace selection is under-specified, and no guidance on output or when to use alternatives is provided.

  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%, so each parameter already has a clear description. The tool description mentions limit, offset, and benefit_id but adds no new semantic details beyond the schema; it also omits workspace_id entirely.

  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 states the operation ('List transactions') and the resource ('for the current workspace'), which distinguishes it from sibling tools like list_accounts or list_benefits. However, it does not explicitly name alternatives or edge cases, so it is not a 5.

  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 on when to use this tool versus other listing tools, nor any prerequisites or exclusions. The description simply states what it does without providing contextual selection rules.

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

• start_loginB
  3.3/5.0
  Behavior1/5

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

  The description states that it sends an email and creates a session, which are side effects. However, the annotations declare readOnlyHint: true, contradicting the described mutation. This is a serious inconsistency. The description fails to disclose the non-read-only nature and does not reconcile with the annotation.

  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, well-structured sentence that front-loads the primary action and outcome, with no wasteful words. All information is directly relevant and immediately useful for an agent.

  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 tool has an output schema (per context signals) and the description mentions a 'short-lived challenge session', which covers the return value. However, the contradiction with the annotation creates a critical gap: an agent relying on annotations would be misled about side effects. This undermines overall completeness despite satisfactory schema and description.

  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 input schema fully documents the 'email' parameter with format, pattern, and a clear description. The description adds minimal value by mentioning email OTP but does not elaborate on syntax or constraints beyond the schema. With 100% schema coverage, baseline 3 is appropriate.

  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 verb ('start'), the resource ('Benepass email OTP login'), and the outcome ('sends a one-time code... returns a short-lived challenge session'). This unambiguously distinguishes it from siblings like complete_login, auth_status, and logout, making it easy for an agent to select the correct first step.

  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 this is the initial authentication step, but it does not explicitly state when to use it versus alternatives or mention any prerequisites (e.g., must have a valid email). No exclusions are provided, but the context of siblings suggests it is the entry point. Lacks explicit guidance on 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.

• logoutB
  3.4/5.0
  Behavior1/5

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

  The annotation readOnlyHint=true directly contradicts the description's promise to delete a session file. Deleting a file is a destructive write operation, not a read-only action. This is a serious inconsistency that misleads the agent about the tool's 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. It states exactly what the tool does, which is appropriate for a zero-parameter, low-complexity operation.

  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?

  While the tool has no parameters and an output schema exists (so return values are covered elsewhere), the description is incomplete because it contradicts the annotation. It also fails to clarify that this is a destructive local action and how it interacts with the server-side session (if at all). The contradiction undermines trust and leaves the agent guessing about actual behavior.

  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 the schema coverage is 100% (empty properties). Since there are no parameters to document, the baseline is 4. The description correctly makes no parameter claims, so no further elaboration is needed.

  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 'Delete' with a clear resource 'local Benepass session file', which unambiguously states the tool's action. It is distinct from sibling tools like start_login, complete_login, and auth_status, all of which handle session lifecycle but not deletion.

  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 usage through the tool name 'logout' and the action 'Delete...session file', but it does not explicitly state when to use this tool versus alternatives (e.g., 'Use when the user wants to end a session' or 'Not for checking status'). The context is reasonably clear but no explicit guidance is provided.

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

• get_hsa_investmentsA
  3.8/5.0
  Behavior4/5

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

  The description goes beyond the readOnlyHint annotation by disclosing the fragile nature ('trying known GET paths', 'First 2xx wins', 'paths may 404'). This is valuable context about failure modes and the operational approach, which the annotation does not cover.

  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 concise sentences with the core purpose front-loaded and the fragility caveat immediately after. No fluff; every clause 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?

  With an output schema present and full schema parameter descriptions, the description covers the essential operational behavior (reverse-engineered, possible 404s). It doesn't mention error handling beyond the 404 hint, but that's acceptable given the fragility warning.

  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% with both parameters described in the schema. The description adds no additional parameter meaning beyond what's already in the schema. Baseline 3 applies.

  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 ('Read HSA investment data') and distinguishes it by describing the reverse-engineered approach. The tool's purpose is clear and unambiguous, differentiating it from siblings like list_transactions or get_hsa_account_details.

  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 explicit guidance on when to choose this tool over alternatives. The description implies it's for investment data, but it doesn't mention when not to use it or point to specific siblings. The reverse-engineered caveat hints at fragility but doesn't route the agent to a more reliable alternative.

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

• list_benefitsA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, covering safety. The description adds that benefits are derived from accounts and that available balance is included, which gives some output context. However, it does not disclose pagination, return format, or any other behavior, so it provides marginal additional value beyond the annotation.

  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 a single efficient sentence that front-loads the core purpose and key detail (available balance) while also noting the endpoint absence. 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?

  With an output schema present and readOnlyHint annotation, the description adequately covers the main use case. It clarifies the data source and output scope, though it omits potential pagination or filtering nuances, which are minor given the schema.

  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 100% with a clear description of workspace_id. The tool description adds no extra detail about the parameter, so it meets the baseline but does not exceed it.

  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 ('enrolled benefits derived from accounts'), and adds valuable detail: it includes available balance and explains why a dedicated endpoint doesn't exist. This clearly distinguishes it from sibling tools like list_accounts or list_transactions.

  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 when to use it (for benefits data) but does not explicitly contrast it with alternatives or state when not to use it. The sibling names and context make the purpose clear, but no formal guidance is offered.

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

• complete_loginA
  3.9/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true, which conflicts with the description's claim that it 'persists a local session'—a side effect. While this is not a full write to a remote resource, it does modify local state. The description explicitly says 'never returns tokens,' which is useful, but the readOnly annotation is questionable. No other behavioral details like rate limits or idempotency are given.

  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 short sentences, front-loaded with the purpose and the source of the challenge session, and the critical side-effect (persists session, never returns tokens) is clearly stated. No wasted words.

  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?

  There is an output schema (not provided in the input but flagged as having one), so the return value is likely documented. The description could mention whether login is idempotent or what happens if OTP is invalid, but for a login completion tool with clear parameters, it is adequate. The possible mismatch with readOnlyHint is a gap.

  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%, so the schema already details each parameter. The description adds minimal value: it names the OTP and challenge_session but does not provide format or relationship details beyond the schema. Since the schema covers everything, baseline 3 is appropriate.

  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 ('Complete Benepass login') with a clear resource lineage ('from start_login'), and distinguishes itself by noting it persists a session and never returns tokens. It clearly differentiates from sibling start_login and auth_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 mentions the prerequisite 'challenge session from start_login' and implies the tool is the second step in a two-step login flow. It does not explicitly mention when not to use it (e.g., after login is complete, use auth_status instead), but the context is reasonably clear.

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

• get_documentA
  3.9/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true already covers safety, and the description adds no further behavioral context (e.g., error handling, rate limits, or return format). It simply restates the action, which is consistent but adds minimal value beyond the annotation.

  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 is front-loaded with the core action and object. Zero wasted words and all content is relevant.

  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 two-parameter fetch tool with a readOnlyHint annotation and an output schema present, the description is sufficient. The agent has all necessary context from the schema and annotations to call 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 description coverage is 100%, so both parameters are already documented with their purposes. The description does not add additional meaning or clarify parameter usage beyond what the schema provides.

  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 'Fetch a single document by id' uses a specific verb and resource, clearly distinguishing it from list_documents. It states the exact operation and scope, leaving no ambiguity.

  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?

  There is no explicit guidance on when to use this tool versus alternatives, though the schema hint that document_id comes from list_documents implies a workflow. No exclusions or alternative names are mentioned, so usage is only implied.

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

• list_accountsA
  3.9/5.0
  Behavior3/5

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

  The readOnlyHint annotation already declares this as a read-only operation, and the description reinforces that by using 'List.' It adds useful context about including balances and scoping to the current workspace, but it does not disclose additional behavioral traits like ordering, pagination, or the fallback default behavior beyond what the schema already states.

  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 a single, focused sentence that front-loads the key verb, resource, and scope. There is no redundant or filler content.

  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 list tool with one optional documented parameter, a readOnlyHint annotation, and an output schema, the description is complete enough for an agent to invoke it correctly. No critical information is missing.

  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 single optional parameter workspace_id is already fully described in the schema, including its default behavior. The description does not need to add parameter details and does not add meaning beyond the schema, 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.

  Purpose5/5

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

  The description clearly states the action ('List'), the resource ('benefit accounts and balances'), and the scope ('current workspace'). This distinguishes it from sibling tools like list_workspaces and list_benefits by specifying accounts and balances rather than workspaces or benefits generally.

  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 makes the basic usage clear for reading benefit accounts in the current workspace, but it does not explicitly explain when to choose this tool over siblings such as list_benefits or list_transactions. Usage is implied rather than directly stated with alternatives.

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

• list_documentsA
  4/5.0
  Behavior3/5

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

  The readOnlyHint annotation already signals a safe, non-mutating operation, so the description doesn't need to restate that. It adds useful context about the document categories and the workspace scoping, but it does not disclose any behavioral traits such as pagination, sorting, or whether only metadata is returned—leaving some ambiguity. Given the annotation covers the safety profile, this feels 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence that states the verb, resource, and scope efficiently, with parenthetical examples of document types. There is zero redundancy, and every word contributes to clarity. It is an exemplary model of concise, structured tool guidance.

  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 low-complexity list operation with one optional parameter, an output schema, and a readOnlyHint annotation, the description is highly complete. It names the document categories, which helps the agent set expectations, and the schema covers parameter behavior. The only minor gap is that it doesn't explicitly point to 'get_document' for retrieving a specific document, but that is more of a usage-guideline nuance than a completeness shortfall for this simple tool.

  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 input schema has 100% coverage: the only parameter, workspace_id, is described as 'Workspace id; defaults to the first employment workspace.' The tool description adds 'current workspace,' which aligns but doesn't introduce new meaning beyond the schema. Since the schema fully documents the parameter, the description adds little extra semantic value, hence the baseline 3.

  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'), a specific resource ('documents'), and the scope ('current workspace'), and elaborates with document categories (statements, plan docs, tax forms). This clearly distinguishes it from the sibling 'get_document', which retrieves a single document. The purpose is unambiguous and immediately actionable.

  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 makes the use case obvious—listing all documents in the workspace—and the workspace scope is clear. However, it does not explicitly contrast with 'get_document' or mention when to prefer one over the other. It also doesn't mention checking 'list_workspaces' if a specific workspace ID is needed, though this is implied. Despite this, an agent would reasonably know to use this tool when a document list is required; a missing explicit exclusion prevents a perfect score.

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

• get_hsa_account_detailsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the description need not repeat safety. It adds value by disclosing a 404 error for non-US users, which is actionable error-prevention context beyond the annotation.

  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 short sentences carry both the core purpose and an error condition, both front-loaded. No filler or redundant restating of the title.

  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 read-only tool with one optional param and an output schema, the description covers the main behavior and a key failure mode. The optional workspace_id is self-explanatory; nothing critical is missing.

  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 100% and the single param workspace_id is already described in the schema. The description adds no extra parameter guidance, so baseline 3 is appropriate when the schema fully covers semantics.

  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 the exact resource ('Health Savings Account details') and scope ('US HSA'), and the verb 'Fetch' is unambiguous. It also differentiates from the sibling get_hsa_investments by implying details, not investments.

  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 specifies a condition ('May 404 for non-US users'), which effectively tells the agent to use it for US users. It does not explicitly name alternatives like get_hsa_investments, but the purpose is clear enough to direct selection.

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

• auth_statusA
  4.3/5.0
  Behavior4/5

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

  The annotation readOnlyHint=true already indicates a safe read, and the description adds a valuable guarantee: 'Never returns secrets.' This goes beyond the annotation by explicitly reassuring the agent about data sensitivity, which is relevant for a tool that shows an email. No contradiction with annotations.

  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 conveys the core functionality and a critical safety guarantee. Every word earns its place; the 'Never returns secrets' clause is front-loaded but follows naturally. No fluff or redundancy.

  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?

  The description is fully sufficient for a zero-parameter, read-only status tool. The output schema (present but not shown) presumably documents return fields like sessionExists and email. The description covers what it does and a behavioral guarantee, leaving no ambiguity for an agent to call it 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?

  The tool has zero parameters, so there is nothing to document beyond the schema. The description effectively communicates what the tool returns (session existence and email), giving the agent meaningful context that the empty schema cannot. With no parameters to clarify, the description carries the full semantic burden and does so well.

  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: 'Show whether a local Benepass session exists, and the logged-in email.' This is a specific verb (show) and resource (local Benepass session) that distinguishes it from sibling tools like start_login, complete_login, and logout, which handle authentication state transitions rather than inspection.

  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 usage as a status check but does not explicitly state when to use it versus alternatives, nor any exclusions. For instance, it doesn't say 'use this before calling other authenticated endpoints' or 'don't use if you need to start a session.' The purpose is evident from context, but explicit guidance is missing.

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

• get_current_userA
  4.3/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true already tells the agent this operation is safe and read-only. The description adds the endpoint and the fact it returns the 'user profile', which is mild additional context. It doesn't disclose things like error behavior, response shape, or authentication state specifics, but given the annotation coverage, a 3 is appropriate—the description adds some value beyond annotations.

  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 a single, direct sentence that conveys the action, resource, and endpoint without any fluff. It is front-loaded with the core purpose and includes the technical detail in parentheses, which is efficient and immediately scannable.

  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?

  Given the tool is a simple read-only GET with no parameters and an output schema exists (even though not included), the description fully covers what an agent needs to know to invoke it correctly. There are no hidden requirements, side effects, or ambiguities. The description is complete for this context.

  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 the input schema is empty. Since there are no parameters to describe, the description is not required to add any parameter semantics. Following the baseline guidance for 0 params, a 4 is appropriate because there is nothing lacking; the description correctly focuses on the operation.

  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 ('Fetch') and a specific resource ('the current Benepass user profile'), which clearly identifies what the tool does. It also includes the endpoint (GET /v2/me/) for technical precision. This differentiates it from siblings like list_workspaces or list_accounts, which target other resources.

  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 purpose is self-evident: to retrieve the current user's profile, which is a foundational call. While no explicit 'use this when' guidance or alternatives are mentioned, the tool's role is obvious from its name and description. Siblings like start_login or complete_login are clearly different steps in the auth flow, so the context is implied if not explicitly stated.

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

• list_workspacesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, covering the safety profile. The description adds beneficial context beyond that: it clarifies the scope (logged-in user's employment and personal workspaces) and the header requirement. It doesn't repeat annotation info and doesn't contradict it. Minor details like pagination or output format are handled by the output schema, so the description's extra context is sufficient.

  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 no filler. The main purpose is stated first, followed by a single relevant constraint. Every word earns its place, and the structure is front-loaded and scannable.

  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?

  With no parameters, an output schema present, and annotations covering read-only behavior, the description covers all necessary details an agent needs to invoke it correctly. The scope and header note are the only operational nuances, and both are included. Nothing is missing.

  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?

  There are zero parameters, so the schema trivially covers all semantics. The rubric assigns a baseline of 4 for zero-parameter tools. The description adds no parameter information, which is appropriate since none exist. No deduction needed.

  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 ('list') and resource ('Benepass workspaces') with clear scope ('for the logged-in user (employment and personal)'). It distinguishes from sibling tools like list_accounts and list_benefits by naming a distinct resource, and the note about not requiring a workspace header further separates it from other tools that may need one. 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.

  Usage Guidelines4/5

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

  It clearly states when to use it (to list Benepass workspaces for the logged-in user) and provides a practical constraint ('Does not require a workspace header'), implying when this tool may be preferred over others that do require a header. However, it doesn't explicitly name an alternative tool or state a scenario where it should NOT be used, so it falls 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.