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

The annotations already signal destructive and idempotent behavior, and the description adds substantial context beyond them: the exact file path (~/.creditkarma-mcp/session or CK_SESSION_PATH), in-memory credential clearing, no network contact, and preservation of synced transactions and host config values. This fully discloses 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.

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

The description is information-dense without redundancy: the primary action and file path come first, followed by the usage condition, then important exclusions. Every sentence adds operational value, and the caveats are separated clearly.

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

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

For a state-clearing destructive tool with no output schema, the description covers all an agent needs: exact target file, environment variable override, in-memory effect, local-only guarantee, and what is intentionally preserved. Nothing necessary for correct invocation or safe reasoning is missing.

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

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%, so the schema carries no semantic burden. With no parameters to describe, the baseline of 4 applies; the description appropriately focuses on behavior instead of parameters.

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

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

The description uses a specific verb ('Forget') and a clear resource ('Credit Karma session on this machine'), then spells out the concrete mechanism: deleting the saved-session file and clearing in-memory credentials. It also distinguishes the tool from its sibling ck_set_session by explicitly naming the session file both tools write to.

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

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

The description states exactly when to use the tool: 'when the user stops using this server or wants their stored login removed.' It also clarifies boundaries by listing what is not affected (synced transactions, CK_COOKIES) and that it is local-only, preventing misuse as a remote logout.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description's 'Return' phrasing is consistent with that. The description adds the per-account grouping context but does not disclose behavioral details like date-range handling, account coverage, or result limitations.

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

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

A single, tightly written sentence that leads with the action and the output scope. Every word earns its place with no repetition or filler.

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

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

For a simple, read-only aggregate tool with optional parameters and no output schema, the description is nearly sufficient. It states what the tool returns, though it could be slightly stronger by explicitly noting that results are filtered by the optional date range.

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

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

Schema description coverage is 100%, with both start_date and end_date documented as YYYY-MM-DD strings. The description adds no further parameter-specific meaning, 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.

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

The description uses a specific verb ('Return'), identifies the resource (account summary), and specifies the exact output shape (per-account debit, credit, and net totals). This clearly distinguishes it from sibling transaction-list and spending-breakdown tools.

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

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

The description implies the tool is for account-level aggregate totals, but it never explicitly states when to use this tool versus the sibling transaction or spending tools. There is no exclusion or alternative guidance, though the intended use is reasonably inferable.

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

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

Annotations already declare readOnlyHint=true, so no destructiveness caveat is needed; the description adds that results are the most recent N transactions. Annotations cover the safety profile, and the description adds modest behavioral context but no details about sort stability, side effects, or edges.

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

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

Two short sentences with no filler: the purpose statement leads, and the relationship to ck_list_transactions follows immediately. Every word earns its place.

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

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

For a one-parameter, read-only convenience tool, the description plus schema is nearly complete. It does not describe the return format, but since this is a shortcut for ck_list_transactions, the shape is implicitly inherited; an explicit note would make it fully complete.

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

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

The only parameter, limit, is fully documented in the schema including its default (25), so the description has little to add. 'N most recent' does map meaningfully to limit, but the schema already carries the parameter semantics.

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

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

The description uses a specific verb-resource pair ('Return ... transactions') with a clear scope ('N most recent') and explicitly ties itself to ck_list_transactions as the broader operation, so an agent can tell it apart from sibling list/spending tools.

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

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

Calling itself a 'convenience shortcut for ck_list_transactions' gives clear context that this is the quick path for recent transactions and names the relevant alternative. It stops short of explicit when-not-to-use conditions, but the shortcut phrasing implies when it is the appropriate choice.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavior: it only includes debit transactions and produces grouped totals. It does not mention sorting or exact output shape, but for a read-only aggregation the provided scope 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.

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

The description is a single concise sentence that front-loads the action and the expected result. Every word earns its place and there is no filler or repetition of schema details.

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

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

For a read-only aggregation tool with all-optional parameters, no output schema, and clear parameter descriptions, the description is largely complete. Explicitly stating the return format would improve it, but 'return totals' already gives sufficient orientation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The tool description adds no parameter-specific detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Group'), the resource ('debit transactions'), the grouping dimension ('by category'), and the result ('return totals'). The category focus clearly distinguishes it from siblings like ck_get_spending_by_merchant and ck_get_account_summary.

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

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

The intended use is implied: call it when you need debit spending totals grouped by category. However, there is no explicit when-to-use guidance, no mention of alternatives, and no exclusions, so the agent must infer the right scenario.

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

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

Annotations declare readOnlyHint=true, which already covers the safety profile. The description adds a meaningful behavioural detail: results are aggregated by total debit spend (not credit or net spend) and ordered by merchant. However, it does not disclose other traits like pagination behavior or that the top-N ordering depends on the limit parameter, so it adds only partial 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.

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

The description is a single, front-loaded sentence with no filler. It communicates the core purpose efficiently and every word contributes meaning.

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

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

For a simple read-only aggregation tool with fully documented parameters, the description is nearly sufficient. It states the core behavior and the readOnlyHint provides safety context. The main gap is the absence of any usage guidance or mention of the output format, but the latter is not required since there is no output schema to complement.

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

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

The input schema already provides 100% parameter coverage with descriptions for all four parameters (limit default, partial category filter, date formats). The description does not add significant meaning beyond the schema; the mention of 'top merchants' loosely maps to the limit parameter but is not explicit. Baseline 3 is appropriate.

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

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

The description states a clear action ('Return') and a specific resource ('top merchants') qualified by a specific metric ('total debit spend'). It is not tautological and is distinct from sibling tools like get_spending_by_category or list_transactions, though it does not explicitly name or contrast those alternatives.

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

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

No guidance is given about when to use this tool versus alternatives such as get_spending_by_category or list_transactions. The description simply states what the tool does, leaving the agent to infer the appropriate context from the name and schema alone.

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

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

Beyond the readOnlyHint annotation, the description adds important behavioral details: 'never returns the credential itself,' makes exactly one authenticated request, and reports a plain-English hint distinguishing three failure modes. It also explains that credential resolution matches 'the way real tools do,' which is valuable context for understanding the tool's behavior.

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

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

The description is three sentences of dense, useful information with no filler. It front-loads the mechanism, then the reporting details, then the caveat and usage trigger. Every sentence earns its place.

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

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

With no output schema, the description adequately conveys what the agent will learn: credential source, acceptance, round-trip time, and a categorized hint. Combined with the read-only guarantee and usage trigger, an agent has enough to decide when to call and what to expect, despite no structured return schema.

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

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

The tool has zero parameters, so there is nothing for the description to add beyond the empty schema. The baseline for 0-parameter tools is 4, and the description appropriately focuses on outputs and usage rather than parameter details.

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

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

The description states a specific verb-resource pair: it resolves credentials and makes an authenticated healthcheck request to creditkrama.com, then reports four concrete outputs. This clearly differentiates it from sibling tools that fetch transactions, spending, account summaries, or run SQL, and the phrase 'Call this when a real tool fails' positions it as a diagnostic tool.

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

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

The description explicitly says 'Call this when a real tool fails and you want to know which hop broke,' giving a clear when-to-use condition. It does not name alternative tools or explicitly state when not to use it, but the failure-driven context implies it is not for routine operations, so guidance is strong but not fully exhaustive.

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

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

The annotations include readOnlyHint=true, which already signals that this is a safe, read-only operation. The description adds the pagination behavior (a strategic trait) but does not disclose details like default pagination limits, maximum page size, or whether results are sorted (e.g., by date). While the description adds some value over annotations, it doesn't provide substantial behavioral context beyond what a read-only hint implies.

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

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

The description is extremely concise, two short sentences, and puts the core function first. It avoids extraneous detail, but it is so brief that it misses opportunities to add clarifying context (e.g., filtering semantics). Still, it is well-structured and efficient.

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

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

With 10 parameters, all optional, and no output schema, the description is thin. It does not explain how filters interact, whether filtering is case-insensitive, what the default sort order is, or how pagination works (e.g., page size limits). Since annotations provide only a read-only hint, the description should carry more weight for usability, but it fails to address these key aspects.

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

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

Schema description coverage is 100%, so each parameter has a basic description (e.g., 'Default 50', 'Partial account name match'). The description adds the concept of 'optional filters' and pagination, but it doesn't add meaning beyond what the schema provides, such as how filters combine (AND logic) or that amount filters use absolute values. Given high schema coverage, the baseline of 3 is appropriate.

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

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

The description states 'List transactions with optional filters. Paginated.', which identifies the primary function (listing transactions) and mentions pagination. However, it does not distinguish this tool from sibling tools like ck_get_recent_transactions, which likely also lists transactions. The description is functional but lacks specificity about scope (e.g., whether it returns all transactions or recent ones).

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

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. With siblings like ck_get_recent_transactions, ck_get_spending_by_category, and ck_query_sql, an agent would benefit from knowing that this tool is for filtered, paginated listing as opposed to recent-only or aggregated views. The description implies it is the general listing tool but does not state exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description substantially enriches this by disclosing that only SELECT is allowed, CTEs are supported, results are capped at max_rows, and truncated: true is returned for larger results. It also names affected tables, giving the agent a clear behavioral model 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.

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

The description is compact and front-loaded with the essential action and constraints. Every sentence contributes meaningful operational detail: the SQL requirement, rejection of non-SELECT, row limits, truncation behavior, and table names. There is no redundancy or filler.

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

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

For a raw SQL tool with no output schema, the description covers what an agent needs to know to invoke it correctly: supported statements, syntax features, result limits, truncation signaling, and available tables. The read-only annotation covers safety, so no additional behavioral disclosure is necessary.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying that CTEs via WITH ... SELECT are supported and listing the available tables, which helps the agent construct valid SQL statements. It also reinforces the max_rows default and truncation behavior already present in the schema.

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

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

The description states a specific verb and resource: 'Execute a raw SQL SELECT query' against the transactions database. It further distinguishes itself from the specialized sibling tools by emphasizing raw SQL and explicitly listing supported tables. The rejection of non-SELECT statements removes ambiguity about what the tool can and cannot do.

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

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

The description clearly conveys that this tool is for raw, read-only SQL SELECT queries and provides practical guidance such as using aggregates or LIMIT/OFFSET paging for large result sets. It does not explicitly name sibling tools as alternatives, but the 'raw SQL' framing and rejection of non-SELECT statements establish a clear use context.

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

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

The annotation only says readOnlyHint: false, which correctly aligns with the description's claim of storing a session. The description adds useful behavioral context: it explains the effect (automatic token refresh) and the mechanics of how to supply input, going beyond the annotation. It doesn't disclose potential overwrite behavior, but that is minor for a setter tool.

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

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

Two sentences cover the purpose and both usage paths. The primary instruction is front-loaded, and the alternative is stated concisely. No redundant filler; each sentence contributes actionable information.

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

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

For a single-parameter tool with no output schema, the description is sufficiently complete. It explains what the tool does, how to obtain the required input, and when an alternative is preferable. It doesn't mention return values, but that is unnecessary for a session-setter.

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

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

Schema coverage is 100%, so the schema already documents the 'cookies' parameter, including the note about CKAT/CKTRKID. The description adds extra meaning by providing concrete steps to extract the cookie from Chrome DevTools and mentioning an alternative that avoids manual copying, which is valuable beyond the schema.

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

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

The description states a clear verb ('store') and resource ('Credit Karma session') with an explicit purpose ('to enable automatic token refresh'). It naturally distinguishes from the sibling data-query tools, which all retrieve information rather than set up state.

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

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

The description gives detailed step-by-step instructions for obtaining the cookie header and also presents an alternative onboarding path (fetchproxy extension) with the implication that the tool is unnecessary when that extension is installed. It doesn't explicitly say 'use this only when you don't have the extension,' but the context makes the choice clear.

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

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

Beyond the readOnlyHint:false annotation, the description discloses meaningful behavior: it writes to a local SQLite database, performs incremental syncs with overlap, can trigger authentication flows, and is bounded/resumable via another_run_needed. This is substantial additional transparency, with no contradiction.

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

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

Three dense sentences with no filler. The purpose is front-loaded, and each sentence adds meaningful behavioral or operational detail.

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

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

For a 2-parameter tool with no output schema, the description covers the key invocation behaviors and the resumption contract. It stops slightly short of fully describing the return payload or failure modes, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds context beyond the schema: it explains the pausing/resuming model and another_run_needed:true, which enriches the meaning of max_pages and force_full.

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

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

The description states a specific verb and resource: 'Sync Credit Karma transactions into the local SQLite database.' This clearly differentiates it from the sibling get/list/query tools, which are read operations rather than write-oriented sync operations.

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

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

The description provides clear operational context: incremental by default, 30-day overlap, auto login/MFA when needed, and resumability. It does not explicitly state when to use this tool versus alternatives or when not to use it, so it falls short of a perfect score.

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