Credit GPS — Canadian credit

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

Beyond the readOnly/idempotent annotations, the description explicitly states it does not make payments, change accounts, fetch external data, or retain tool inputs. This gives agents a clear, non-destructive mental model and matches the annotations exactly.

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 front-loaded with the primary use case and return value, followed by differentiation and behavioral caveats. Every sentence contributes distinct information without 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 read-only calculation tool, the description covers purpose, output, prerequisites, sibling distinctions, and side-effect guarantees. It is fully sufficient for an agent to decide when and how to invoke it correctly.

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% with rich parameter descriptions already present, so the baseline applies. The outer description only restates APR requirements and minimum-payment fallback, adding little semantic value 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 opens with concrete use-case examples ('if I pay $200 a month...') and clearly states the output: payoff duration and interest paid. It also distinguishes this cost-question tool from reporting-oriented siblings like get_reported_snapshot and simulate_paydown.

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?

It explicitly says when to use the tool ('Use this for...') and when not to, pointing to get_reported_snapshot or simulate_paydown for reporting questions. It also provides a prerequisite (purchase APR) and the consequence of omitting it, leaving little room for misuse.

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 indicate read-only, idempotent, and non-destructive behavior, and the description adds valuable context: 'does not make payments, change accounts, fetch external data, or retain tool inputs.' It also explains the utilization-versus-rate trade-off, setting accurate expectations for the kind of answer returned.

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?

Every sentence earns its place: trigger, output shape, trade-off rationale, and boundary statements. The description is information-dense without repeating schema details, and the most decision-relevant information is front-loaded.

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?

Given the rich input schema, existing output schema, and annotations covering safety and side effects, the description supplies the missing selection and expectation-setting context. An agent has everything needed to decide when to invoke it and what to expect back.

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%, and every parameter already has detailed documentation in the input schema. The description refers to 'the amount given' and 'supplied figures' but adds no parameter-level meaning 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 opens with an explicit trigger—'Use this when someone asks which card to put a purchase on'—and names concrete outputs: the card with least utilization impact, the cheapest card to carry, and the trade-off when they differ. This clearly defines the tool's verb, resource, and purpose, and distinguishes it from sibling planning/explanation 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?

It states a clear usage trigger('someone asks which card to put a purchase on') and scope ('Calculates scenarios from supplied figures'). It does not explicitly name alternative sibling tools or say when not to use this tool, so it falls just short of full exclusionary guidance.

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 annotations, the description discloses meaningful behavioral limits: it cannot save entries, retrieve score history, fetch live data, or change accounts. This gives agents a precise model of what the tool can and cannot do.

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 front-loaded with usage guidance and keeps each sentence informative. It is slightly dense, but given the 0-parameter schema and the need to explain both the tool's purpose and limitations, the length is justified.

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 no-parameter informational tool with an output schema, the description covers the key scenarios, the data privacy question, the manual entry workflow, and the tool's limitations. Nothing essential 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, so the baseline is 4. The description adds that it returns bundled reference material 'optionally filtered or calculated from inputs,' which is useful context even though no schema parameters exist.

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 names a specific resource ('Credit GPS' itself) and enumerates concrete use cases: explaining what it is, who made it, data storage, shortened answers, and bureau report entry. This clearly differentiates it from sibling tools that explain credit mechanics or simulate paydowns.

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 begins with 'Use this when someone asks...' and lists the exact triggers. It does not name sibling tools or state when not to use it, but the context is clear enough for an agent to route appropriately.

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 description fully discloses the tool's behavior: it calculates utilization before/after, shows whether the limit leaving the denominator, and indicates if utilization crosses a band upward. It also states it does not make payments or change accounts, aligning with the readOnlyHint and destructiveHint annotations. 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.

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

The description is well-structured and succinct despite covering many nuances. It packs a lot of information into a compact space, using clear clauses and examples. The repetition of what it does not do is purposeful for emphasis and does not feel verbose.

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?

Given the tool's complexity (multiple card parameters, optional inputs, behavioral edge cases), the description covers all necessary context. It explains the role of each key parameter, the output of the calculation, and the tool's non-destructive nature. The presence of an output schema further reduces the need for description-level output details.

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 schema has 100% description coverage, but the tool description adds crucial semantic details beyond the schema: cardName supports partial matching, today's date should be passed to avoid UTC fallback, and APR 0 means a real interest-free rate, not unknown. These clarifications enhance parameter understanding.

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 clearly states the tool's purpose: to answer questions about cancelling, downgrading, or consolidating cards by explaining utilization impact. It also explicitly says what it does not do (does not close, cancel, or change cards), leaving no ambiguity about its scope.

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?

It provides concrete guidance on when to use the tool (questions about cancelling/downgrading/consolidating), how to provide card data (optional, with examples of naming), and what happens if no cards are supplied. It also warns against passing 0 for unknown APR or minimum payment, which is critical for accurate estimates.

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 communicate read-only and idempotent behavior, and the description adds useful context: it 'does not fetch live data or change accounts' and returns 'bundled reference material, optionally filtered or calculated from inputs.' This goes beyond the structured hints without contradicting them.

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 dense but each sentence earns its place: when to use, what content is returned, and behavioral limitations. It front-loads the usage trigger and avoids filler or repetition.

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 one optional enum parameter, rich annotations, and an output schema, the description fully covers what the agent needs: the use case, the scope of content, the output nature, and the lack of live data access or side effects. Nothing essential 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 schema already covers the single optional topic parameter at 100%, including an enum and instructions to omit for all topics. The description reinforces the topics in prose but does not add new parameter-level meaning, 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 clearly identifies the tool as the one for explaining Canadian credit mechanics, with specific verbs like 'Use this for a requested explanation' and a detailed list of covered topics. It does not explicitly name or contrast sibling tools such as explain_when_issuers_report or describe_credit_gps, so it stops just short of full differentiation.

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 first sentence gives a direct usage condition: use it for requested explanations of Canadian credit scores, reports, utilization, or reporting timing. It does not list exclusions or explicitly name alternatives, but the context is clear enough for an agent to select it from the sibling set.

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 mark it read-only and idempotent, and the description adds non-obvious behavioral context: it returns bundled reference material, optionally filters or calculates based on inputs, does not fetch live data, and does not change accounts. It also explains a key timing nuance (the 30-day gap) that shapes what the agent can promise the user.

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 dense but not padded; the first sentence leads with the trigger cases and the key question. It is slightly long, with a compound final sentence, but every clause carries decision-relevant 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?

With one optional parameter, full schema coverage, rich annotations, and an output schema present, the description covers the main usage trigger, the Canadian-specific content, the non-live behavior, and the consequence for the user's file. Nothing essential is missing 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.

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

The schema already documents daysPastDue with 100% coverage, and the description adds the practical effect: 'Changes which part of the answer leads.' This is meaningful extra semantics beyond the schema, though modest.

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?

Description opens with explicit use cases ('missed, late, or nearly-late payment', 'how long will this hurt me') and names the exact resource: what happens when a Canadian credit card payment is missed, including the 30-day gap, R1-R9 scale, and retention duration. This scope is specific enough to separate it from siblings like explain_retention_periods or explain_when_issuers_report.

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?

It says plainly when to use the tool and what it is not for ('does not fetch live data or change accounts'), which gives clear decision context. It does not explicitly name sibling tools as alternatives or state a when-not-to-use condition, so it stops 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.

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

The description explicitly states that the tool 'does not fetch live data or change accounts,' aligning with the readOnlyHint and destructiveHint annotations. It also clarifies that it returns bundled reference material with source links, setting accurate expectations for 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 fairly concise and front-loads the primary use case, but it repeats the 'Returns...' phrase twice. This minor redundancy does not significantly harm clarity.

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?

The description provides enough context for a no-parameter informational tool: it names the topic, the categories covered, that durations vary by bureau and province, and that source links are included. It does not specify output format, but for a simple reference lookup this is adequate.

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 effectively 100% with an empty properties object. The description does not need to explain parameters, so the baseline score of 4 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 explicitly states the tool answers 'how long will this stay on my credit report' and lists the specific retention categories covered (closed accounts, late payments, collections, etc.). This clearly distinguishes it from sibling tools like explain_missed_payment or explain_when_issuers_report.

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?

It provides a clear use case ('use this for any how long will this stay question') but does not explicitly mention when to prefer alternative tools such as explain_missed_payment or simulate_paydown. Some implicit differentiation exists via the retention focus, but no direct exclusions are stated.

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 description honestly discloses the limitations: no exact reporting day and no verified per-issuer transmission calendar. It also states the tool is read-only and does not change data, which aligns with the annotations. This transparency helps the agent set correct expectations.

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 generally concise but contains slight redundancy: 'This bundled reference has no verified per-issuer transmission calendar and returns no exact reporting day' restates what was already implied in the previous sentence. Still, it is well-structured and front-loaded with usage guidance.

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?

Given that there is no input schema and no output schema details, the description is complete enough: it explains what the tool returns (general cadence, differences between bureaus) and what it lacks. It could mention the output format, but for an explanatory tool this is not a major gap.

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 to explain. The baseline score of 4 is appropriate because the description does not need to elaborate on parameters, and it correctly avoids inventing any.

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 clearly states the tool's purpose with specific example questions ('when will this show up on my credit report') and the resource it explains (issuer reporting to bureaus). It differentiates itself from siblings by focusing on the timing of reporting, not on other credit mechanics.

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?

It explicitly tells the agent when to use the tool (for questions about reporting cadence) and what it does NOT provide (exact days, verified per-issuer calendar). It also states it does not fetch live data or modify accounts, preventing misuse.

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 description goes beyond the annotations by explaining that the tool 'looks nothing up on any account,' the estimate is purely 'arithmetic on the date supplied,' and it 'does not fetch live data or change accounts.' This aligns with readOnlyHint=true and destructiveHint=false while adding meaningful context about the operational scope. It also explains the regulatory 21-day grace period, which clarifies the estimate logic.

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 three-sentence block that front-loads the primary usage. Every sentence carries functional information, but the aside about being 'the one most people have never been shown' is promotional and not needed for tool selection. It is reasonably concise and well ordered.

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?

The description covers what the tool returns, when to use it, the arithmetic basis of the estimate, and clear operational boundaries (no live data, no account changes). With an output schema present, it does not need to enumerate return fields. An agent has enough context to select and invoke the tool correctly.

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%: both issuer and dueDate have detailed descriptions in the input schema. The tool description restates that dueDate produces a derived estimate and that issuer only tailors wording, but it adds little new parameter-level meaning beyond what the schema already provides. Baseline 3 applies.

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 clearly states the tool's function: it returns the ways to find a Canadian credit card's statement closing date and derives an estimated closing date from a payment due date. The opening 'Use this whenever someone does not know their statement closing date' names a specific use case, and the phrase 'the date every other tool here depends on' helps distinguish it from siblings.

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 first sentence explicitly gives trigger conditions: 'Use this whenever someone does not know their statement closing date, or gives a payment due date and asks what to pay.' It also states what the tool does not do ('does not fetch live data or change accounts'), which helps rule out inappropriate use. However, it does not name alternative sibling tools or give explicit when-not-to-use conditions beyond those implicit in the description.

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 already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes beyond annotations by clarifying that nothing is scheduled or executed, the plan is returned for the person to act on themselves, and the tool does not make payments, change accounts, fetch external data, or retain inputs. This is rich, accurate behavioral disclosure.

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 sentences, each earning its place: when to use it, what it returns and how, and what it does not do. The most important routing information is front-loaded in the first sentence, and there is no redundancy with the schema.

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?

Given a rich schema, an output schema, and comprehensive annotations, the description covers the key contextual gaps: use case, output structure, side-effect absence, data handling, and scope boundaries. An agent has enough to invoke it correctly without additional information.

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 carries the parameter documentation. The description adds little beyond naming the three goal values and saying it "calculates scenarios from supplied figures," which is a reasonable baseline score when the schema already fully documents each field.

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: "Returns an ordered plan" for one of three named goals (raise_score, pay_down_balances, or build_credit). It also distinguishes this multi-step planning tool from a single-next-action tool, making its purpose clear and differentiated from siblings like get_next_move.

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 opening phrase "Use this when someone wants more than the next single action" gives clear usage context and implicitly contrasts with the single-action sibling tool. It does not explicitly name alternatives or state when not to use it, but the guidance is specific enough to route an agent correctly.

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 description adds meaningful behavioral context beyond the annotations: it states that the tool returns bundled reference material, does not fetch live data, and does not change accounts. It also discloses coverage limitations for home-country credit import, which is valuable given the openWorldHint=false annotation and the partial coverage caveat.

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 well structured and front-loaded with the core usage statement, followed by concrete path details and caveats. It is a little long, but each sentence contributes useful information: scope, path content, parameter guidance, coverage limitations, and side-effect disclosure.

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?

Given that an output schema exists and annotations already convey read-only, idempotent, non-destructive behavior, the description covers what an agent needs to know: target audience, expected content, parameter influence, coverage limitations, and the fact that no live data or account changes are involved. Nothing important appears 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of each parameter in context: homeCountry determines whether the credit-import route is open, and monthsInCanada focuses the answer on the relevant phase. This is more useful than the raw schema alone.

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 opens with a specific audience and task: building credit as an immigrant, newcomer, international student, or temporary resident in Canada. It then enumerates the concrete components of the returned path, such as steps before a SIN arrives, home-country history import, and first tradeline, making the tool's scope clear and distinct from the sibling 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 clearly states when to use the tool: 'Use this for any question about building credit as an immigrant, newcomer, international student, or temporary resident in Canada.' It does not explicitly name alternatives or exclusions, but the audience and purpose are specific enough that an agent can identify the intended context without confusion.

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 already signal read-only, idempotent, and non-destructive behavior. The description adds valuable detail beyond those hints: 'does not make payments, change accounts, fetch external data, or retain tool inputs,' and it discloses the planning-assumption caveat about issuer reporting dates. 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.

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

The description is three dense, front-loaded sentences with no filler; the trigger conditions appear first and the caveats are compactly grouped. The final negative list is slightly long but each item serves the transparency goal.

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?

Given the rich schema, strong annotations, and an output schema, the description sufficiently covers invocation triggers, data scope, assumptions, and side-effect limitations. It doesn't explain the priority calculation, but that is reasonable to leave to the output schema and the tool's behavior.

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 schema covers 100% of parameters with highly detailed descriptions, including defaults, units, and edge cases. The tool description only adds thematic hints like 'which card, how much, and by which date,' which doesn't materially extend the schema's already comprehensive parameter documentation.

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 ('Returns') and resource ('the single highest-priority action') and enumerates the exact user questions it answers ('what to pay first, what to do next, or how to lower utilization'). It distinguishes itself from siblings like simulate_paydown or get_credit_plan by emphasizing 'single' action rather than a plan or timeline.

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?

It explicitly states when to use the tool with three concrete trigger phrases. However, it doesn't name alternatives or state when not to use it, so it stops short of full routing guidance.

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 readOnly, idempotent, non-destructive, so the description's safety claims are consistent. Beyond that, it adds important behavioral context: it is a pure calculation engine that does not make payments, change accounts, fetch external data, or retain inputs, and it flags the key modeling boundary that it does not determine future bureau-reported balances.

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 but dense, front-loads the trigger phrases, and every sentence carries distinct information. The non-goals list in the last sentence is a single tight clause that prevents misuse without padding.

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 an output schema present, annotations covering the safety profile, and 100% parameter documentation, the description adds the one crucial piece missing from structured data: the boundary between today's balance and issuer-reported balance. Nothing an agent needs to select or call the tool correctly 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?

Schema coverage is 100%, so the baseline is 3. The description still adds high-value semantics by identifying the three parameters that 'drive everything' (limit, statement balance, statement closing date), clarifying the utilization read uses statementBalance, and noting that targetUtilization defaults to one point under 30%. This goes beyond what the schema alone conveys.

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 opens with concrete user intents ('how their cards look, where they stand, which card is the problem') and names the exact outputs: utilization from supplied balances, days to closing date, hypothetical payment to reach target. It also distinguishes itself by explicitly stating it does not determine bureau-reported balances.

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 specifies when to use it ('when someone asks how their cards look, where they stand, or which card is the problem') and gives clear non-goals. It does not explicitly name sibling alternatives like describe_credit_gps or get_credit_plan, but the listed exclusions effectively tell an agent when this tool is not the right fit.

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 indicate read-only, idempotent, non-destructive behavior, and the description reinforces this by stating it 'does not make payments, change accounts, fetch external data, or retain tool inputs.' This adds meaningful behavioral context beyond the annotations and contains 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?

The description is concise, front-loaded with usage guidance, and free of redundant wording. Every sentence contributes meaningful information: when to use it, what it returns, and what it avoids doing.

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?

Given the rich output schema and detailed input schema, the description provides sufficient context for an agent to decide when to invoke the tool. It explains the primary use case, the nature of the returned events, and key behavioral boundaries, so nothing essential 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 input schema is fully described with detailed parameter explanations, so schema coverage is high. The tool description itself adds little parameter-specific meaning beyond saying 'supplied figures,' but it does not need to because the schema already provides comprehensive semantics. This aligns with the baseline for high schema coverage.

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 clearly states the tool's purpose: it returns upcoming statement-related dates and explains timing questions like why closing date differs from due date. It uses specific verbs ('returns', 'calculates') and the resource is evident from the tool name and description, making it distinguishable from siblings focused on other tasks.

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 when to use the tool ('Use this when someone asks about timing, what is coming up, or why the closing date differs from the due date') and clarifies what it does not do. However, it does not explicitly name alternative sibling tools or state when not to use it in favor of those, so it falls slightly short of full alternative guidance.

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 readOnly, idempotent, and non-destructive hints. The description goes beyond them by disclosing that results are dated reference examples, grouped by credibility tier, includes per-bureau reporting details, flags warning signs, and explicitly states it does not fetch live data or change accounts. This substantially enriches the behavioral model 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 front-loaded with the core purpose and contains valuable context. However, it repeats the 'Returns...' idea twice ('Returns the products...' and 'Returns bundled reference material...'), and the single-bureau insight, while useful, adds length. It is slightly more verbose than needed for a single optional parameter.

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 low-complexity tool with one optional parameter, an output schema, and annotations, the description covers everything an agent needs: what it returns, how results are grouped, which bureau details are included, the non-live reference nature, and provider confirmation caveat. No critical operational detail 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 schema already provides 100% coverage for the only parameter, including the enum values and their meaning. The description adds only a general note that results are 'optionally filtered or calculated from inputs' and maps the output grouping to tiers, but it does not meaningfully improve on the schema's own parameter documentation.

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 opens with a specific action ('retrieve dated reference examples of Canadian secured cards and credit-building products') and clearly states the resource and scope. It also distinguishes itself from siblings by emphasizing reference-only material and warning-sign flags, so an agent can tell it apart from tools like compare_cards_for_purchase or explain_canadian_credit_mechanics.

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?

It gives clear context for using the tool: retrieve reference examples, confirm current terms with the provider, and expect non-live, non-mutating behavior. However, it does not explicitly name sibling alternatives or state when to prefer those instead, so it stops short of the full 5.

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 annotations (readOnly, idempotent, non-destructive), the description adds substantial transparency: 'It is a calculation only; no payment is made' and explicitly states it 'does not make payments, change accounts, fetch external data, or retain tool inputs.' This fully discloses the tool's side effects and non-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 appropriately sized but contains some redundancy, such as repeating the calculation nature in 'Returns a what-if' and 'Calculates scenarios'. It is still clear and well-organized, but could be trimmed slightly without losing 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?

Given the tool's moderate complexity and the presence of a separate output schema, the description covers all essential aspects: purpose, output scope, and limitations. It does not address edge cases like multiple cards or overpayment, but these are likely covered by the schema and are not critical for an agent deciding to invoke the tool.

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 extensive descriptions for all parameters (100% coverage), including nuanced warnings like the meaning of 0 for creditLimit and aprPercent. The main tool description adds no additional parameter semantics, so the baseline score for high schema coverage applies.

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 clearly states the specific trigger ('when someone asks what happens if they pay a particular amount, or wants to compare two amounts') and the precise output ('reported utilization before and after, per card and blended'). It also explicitly distinguishes what it does not do ('No score change is predicted'), making the tool's purpose unambiguous.

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

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

The description provides a clear positive use case but does not mention when to prefer an alternative tool or when not to use it. While it implies that it is only for calculation and not for actual payments, it lacks explicit comparison against sibling tools, leaving some ambiguity about boundary conditions.

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