Server Quality Checklist

Tool Scores

• auth_exchange_codeA
  4.5/5.0
  Behavior5/5

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

  With no annotations present, the description carries the full behavioral burden, and it handles this well. It discloses that tokens are stored locally, that subsequent tool calls use them automatically, that codes are single-use and time-limited, that state mismatches trigger CSRF protection, and that expired/invalid codes require restarting with auth_get_url.

  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 organized into short, scannable sections — WHEN TO USE, REQUIRED, RETURNS, ERRORS — and every section contributes necessary information. The core purpose is front-loaded before details, and there is no filler or repetition beyond useful emphasis.

  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 two-parameter tool with no output schema and no annotations, the description is complete: it explains the trigger event, inputs, return shape, side effects, error cases, and recovery path. An agent has everything needed to decide when to call this tool and what to do afterward.

  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 already provides strong descriptions for both parameters, including examples and the CSRF-matching requirement, so schema coverage is 100%. The description mostly restates this information rather than adding new parameter-level meaning, which matches the baseline of 3 for high schema coverage.

  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 a specific verb and resource — "Exchange an OAuth authorization code for access and refresh tokens, completing the FreshBooks connection." This clearly distinguishes the tool from siblings like auth_get_url (which creates the auth URL) and auth_revoke (which revokes access). The purpose is unambiguous.

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

  Usage Guidelines4/5

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

  The description gives strong context: use it immediately after auth_get_url returns a redirect code, and call it only once because codes expire quickly. It does not explicitly name alternatives or state when NOT to use it, but the timing and sequencing guidance make the correct invocation context clear.

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

• auth_get_urlA
  4.7/5.0
  Behavior4/5

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

  Since no annotations are provided, the description carries the full burden. It clearly discloses that the tool generates a URL and CSRF token, takes no arguments, and specifies the exact return shape plus the workflow leading to auth_exchange_code. It does not mention the CSRF token expiration or the need to store it, which would be minor additions.

  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 efficiently structured with a one-sentence purpose, a WHEN TO USE list, a RETURNS example, and a numbered WORKFLOW. Every section adds distinct, non-redundant guidance and front-loads the core action.

  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?

  It covers when to call the tool, what it returns, how the user participates, and which tool to call next. Given there are no parameters, no annotations, and no output schema, the description provides a complete operational picture for an agent to select and 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 input schema is empty and the description explicitly states 'TAKES NO ARGUMENTS.' With zero parameters, per the rubric the baseline is 4; the statement aligns with the schema and no further parameter semantics are 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 opens with a specific verb and resource: 'Generate an OAuth 2.0 authorization URL and a CSRF state token for the FreshBooks sign-in flow.' The WHEN TO USE section also implicitly distinguishes it from sibling tools by describing status checks and later code exchange, making the tool's unique role unmistakable.

  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?

  The WHEN TO USE section lists three concrete triggers, including 'auth_status returns { connected: false }', explicit user phrases, and re-authentication after a revoked session. It also routes the caller to auth_exchange_code for the follow-up step, clarifying when this tool is the right choice versus its siblings.

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

• auth_revokeA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full disclosure burden and succeeds admirably. It states the destructive consequence (deletes all stored tokens), and the NOTE section reveals the critical side effect that all accounting/time-tracking tools will return auth errors afterward until the companion flow is re-run. This is exactly the post-condition disclosure an agent needs before invoking a destructive action.

  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?

  Every section earns its place: purpose, WHEN TO USE scenarios, argument confirmation, return shape, and post-condition warning. The bolded section headers make it scannable, and there is zero filler or repetition of schema 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 zero-parameter, no-output-schema tool, this definition is complete. It supplies a sample return value, names the sibling steps to re-authenticate, and discloses the failure mode that follows invocation. Nothing an agent needs to call it correctly or anticipate its effects 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?

  The tool takes zero parameters and the schema is fully covering (100%), so the baseline is 4. The description reinforces this with an explicit 'TAKES NO ARGUMENTS' line, which removes any doubt. There is nothing further parameters could require.

  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?

  Opens with a specific verb and resource: 'Revoke the current FreshBooks OAuth session and delete all stored tokens.' This clearly distinguishes it from siblings auth_status (check state), auth_get_url (start new flow), and auth_exchange_code (complete flow), so an agent can tell them apart without opening schemas.

  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?

  Provides an explicit WHEN TO USE section with unmistakable trigger phrases ('disconnect FreshBooks', 'sign out', 'remove my FreshBooks connection'), a concrete switching-accounts scenario, and a security rationale. It even routes the agent through the sibling flow (auth_get_url → auth_exchange_code) for re-establishing the connection.

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

• auth_statusA
  5/5.0
  Behavior5/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 — and it delivers by specifying the exact return contract in both states ({ connected: true, userId, accountId, businessId, email, expiresAt } vs { connected: false }) and asserting it is 'safe to call anytime.' It also explains what the returned IDs mean for downstream tools, giving the agent a workable mental model without any annotation safety cues.

  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 organized into labeled sections (WHEN TO USE, RETURNS connected, RETURNS no session, NEXT STEPS) with no wasted sentences, and the lead sentence's summary and front-loaded. The formatting is scannable, important for an agent parsers, and every section adds new information rather than repeating the schema.

  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?

  Despite having no output schema and no annotations, the description fully covers what an agent needs: the no-argument case, the return shape in both success and failure states, and the follow-up action for each branch. Any complexity that would otherwise need structured fields is already handled in prose.

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

  Parameters5/5

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

  The tool has zero parameters, so the baseline is already 4. The description additionally states 'TAKES NO ARGUMENTS — safe to call anytime,' explicitly confirming to an agent that no arguments are required and removing any doubt about invocation. Nothing is left for the schema to explain.

  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 a specific verb-resource pair: 'Check whether FreshBooks is connected and return the active session details.' This is unambiguous against the sibling set (auth_get_url, auth_exchange_code, auth_revoke), whose purposes are distinct. The NEXT STEPS section further reinforces its role as a status probe, not an auth flow mutator.

  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?

  The description explicitly states WHEN TO USE: call first in any workflow, when the user asks about connection state, and to diagnose auth errors. It also gives the exclusion and routing by naming the alternative directly: 'If connected: false → call auth_get_url to start OAuth.' This gives an agent deterministic selection guidance.

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