Server Quality Checklist

Tool Scores

• yoto_logoutA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns with that. The description adds useful context by clarifying it only affects a local record and does not call a remote API, which is valuable behavioral information beyond the annotations. However, it doesn't disclose whether this invalidates any session state or affects other local 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 short sentences with no wasted words. The key behavioral fact (local only, no remote API) is front-loaded and clearly stated.

  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, no-output-schema tool, the description is nearly complete. It clearly states the action and the local-only scope. The only minor gap is not explaining what happens after logout (e.g., whether the user must re-authenticate) or how this relates to sibling auth tools, but this is a minor omission given the tool's simplicity.

  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 the schema is trivially complete. The description adds no parameter details, but none are needed. Baseline 4 for zero params is appropriate.

  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 action ('Delete the local Yoto token record') and the resource ('local Yoto token record'). It distinguishes itself from remote API calls, which helps differentiate it from sibling auth tools. However, it doesn't explicitly name a sibling alternative, so it doesn't fully distinguish from all siblings.

  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 for local logout/session cleanup and explicitly notes it does not call a remote API, which gives some context. However, it doesn't state when to use this vs yoto_auth_start or yoto_auth_status, nor does it mention any prerequisites or side effects like whether the user must be authenticated first.

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

• yoto_auth_completeA
  3.8/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description's 'finish the login' is consistent with these (a mutating but non-destructive state transition), so there is no contradiction. However, the description adds little beyond annotations — it doesn't disclose what happens to the pending state, whether tokens are persisted, or behavior when no pending login exists. Useful context is minimal.

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

  Conciseness4/5

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

  A single sentence that front-loads the action and includes the triggering condition with zero wasted words. It is appropriately sized for a parameterless tool. It could add a brief usage caveat, but what's there is tight and relevant.

  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?

  With 0 parameters and no output schema, the description carries the burden of explaining the flow. It states the trigger ('after the browser callback arrives') but omits the key precondition that yoto_auth_start must have been invoked to create the pending state, and it doesn't describe the resulting state transition or what indicates success. Adequate but leaves the agent to infer the call sequence.

  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 0 parameters (schema coverage vacuously 100%), so the baseline is 4. The description adds conceptual meaning by naming PKCE and the local-pending state, which helps the agent understand the flow even though no arguments are supplied. Some small credit is justified for this framing.

  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 ('finish') and a specific resource ('pending local PKCE login') plus the trigger condition for when it applies. It clearly distinguishes from siblings: yoto_auth_start begins the flow, yoto_auth_status checks state, yoto_logout ends the session — this one completes it. An agent can tell exactly what this tool does without inspecting 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 Guidelines3/5

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

  The phrase 'after the browser callback arrives' gives a timing condition, and the PKCE flow context implies this runs after yoto_auth_start. However, there is no explicit statement of preconditions (e.g., 'only after yoto_auth_start and a successful browser redirect') or exclusions telling the agent when it should use yoto_auth_status instead. The usage is implied but not spelled out.

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

• yoto_list_cardsA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true; the description's 'No write operation' is consistent but redundant. It does add the 'authenticated user’s' scoping, which clarifies whose cards are returned, though it provides no detail on pagination, sorting, or output shape.

  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 short front-loaded sentences with no unnecessary elaboration. The first sentence communicates the core purpose immediately; the second reinforces read-only behavior, though it is somewhat redundant with the readOnlyHint annotation.

  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 list operation, the description is substantively complete: it identifies the resource and the authenticated scope, and annotations cover safety. It does not describe return fields or pagination, but no output schema exists and the operation is simple enough that this is a minor gap.

  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 coverage is 100%, so there is no parameter documentation burden. The baseline of 4 for parameterless tools applies, and the description correctly focuses on behavior rather than inputs.

  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 ('Read') and resource ('authenticated user’s MYO cards'), making the operation's scope unambiguous. The name yoto_list_cards is further clarified as a list operation, distinguishing it from yoto_get_card without needing to open 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 Guidelines3/5

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

  The description implies the tool is for retrieving the authenticated user's MYO cards, but it does not explicitly say when to prefer it over siblings like yoto_get_card or yoto_list_devices. There is no exclusion guidance or alternative routing, leaving usage mostly to inference.

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

• yoto_get_cardA
  4/5.0
  Behavior3/5

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

  The 'No write operation' phrasing repeats what the readOnlyHint annotation already establishes, adding little new behavioral information. It does not mention authentication requirements, error behavior, or open-world return semantics, though the annotations reduce the burden here.

  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 extremely compact: a concrete first sentence states the core operation immediately, and the second sentence reinforces the read-only nature. There is no filler or unnecessary detail.

  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 single-parameter, read-only tool with sibling guidance and annotations, this is largely complete. It tells the agent what to do and confirms no mutation, but it leaves minor gaps such as the meaning of 'MYO' and expected authentication context.

  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 carry must some compensating meaning. 'By ID' maps directly to the cardId parameter, but it does not explain where the ID comes from or what format constraints apply beyond the schema's own maxLength and minLength.

  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 MYO card by ID.' It clearly distinguishes this single-card retrieval operation from siblings like yoto_list_cards and the authentication tools, so an agent can identify its purpose instantly.

  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 makes clear the tool is for fetching exactly one card using its ID. It does not explicitly name yoto_list_cards as the alternative when all cards are needed, so while the intended usage context is clear, explicit when-not guidance is absent.

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

• yoto_list_devicesA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it returns 'names and status' and explicitly states it does not control or modify devices, which is consistent with the annotations. However, it does not disclose details like whether authentication is required or what 'status' includes, so it provides only modest additional behavioral context beyond the 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 concise sentence with the primary purpose front-loaded ('Read linked Yoto player names and status') and a clarifying negative statement following. Every word earns its place, and the structure makes the tool's intent 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?

  This is a simple, zero-parameter, read-only tool with annotations covering its safety profile. The description specifies exactly what is returned (player names and status) and limits scope to linked devices. No output schema exists, but for a list operation of this simplicity, the description provides sufficient information for an agent to invoke it correctly.

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

  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 trivially 100%. The description correctly focuses on what the tool returns rather than parameter details. No parameter information is needed, so the baseline of 4 for 0-parameter tools 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?

  The description uses a specific verb ('Read') and a clear resource ('linked Yoto player names and status'), making its purpose immediately obvious. The explicit negative clause 'Does not control or modify devices' further distinguishes it from any mutation tools and reinforces its read-only scope. It is clearly differentiated from siblings like yoto_list_cards and yoto_get_card by naming the resource type (devices).

  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 provides clear context that this tool is for reading linked devices and retrieving their names and status, and it explicitly states that it does not control or modify devices. While it does not name alternative sibling tools or give explicit when-not-to-use conditions, the usage context is clear, and the negative clause serves as a partial exclusion.

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

• yoto_auth_statusA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true; the description adds the useful constraint that it reports token presence without returning the token itselfcars. This is meaningful behavioral disclosure for an auth-related 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?

  Single sentence, front-loaded with the core action, no filler or redundancy. Every word 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 simple, parameterless status check, the description sufficiently conveys purpose and the key security-relevant constraint (no token returned). With no output schema present, the 'whether' wording implies a yes/no result, which is adequate for this complexity level.

  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 schema has zero parameters)Skip parsing: 0 parameters baseline of 4; nothing more needs to be compensated.

  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?

  Description uses a specific verb ('show') and resource ('whether this local server has a Yoto refresh token'), clearly distinguishing a status check from the sibling auth_start/auth_logout tools. 'Without returning tokens' further narrows the tool's behavior and prevents confusion with credential-returning operations.

  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 immediately clear as a read-only auth status check, and sibling names imply the surrounding auth flow. It does not explicitly state exclusions or when to prefer this over alternatives, but for a zero-parameter status tool the context is sufficient.

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

• yoto_auth_startA
  4.5/5.0
  Behavior4/5

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

  Annotations provide limited behavioral detail (openWorldHint=true, readOnlyHint=false), and the description adds that a URL is returned, must be opened, and requires calling yoto_auth_complete to finish. No contradiction with annotations was found.

  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 that are front-loaded with the primary action and include the necessary next step. No filler or redundant detail.

  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 zero-parameter tool with no output schema, the description explains the returned URL and the required completion call, making the tool self-contained for an agent to invoke 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 description does not carry parameter responsibilities. Baseline 4 is appropriate; no supplemental parameter explanation 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 states a specific verb 'Start' and resource 'Yoto Authorization Code + PKCE login', and explicitly mentions the follow-up tool yoto_auth_complete, distinguishing it from siblings like yoto_auth_status or yoto_logout.

  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 gives an explicit sequential workflow: open the returned URL, then call yoto_auth_complete. This is clear guidance, but it lacks explicit when-not conditions, such as whether to skip when already authenticated.

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