Credit GPS — Canadian credit

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description agrees with them while adding a real precondition: without the card's purchase APR no timeline is returned, because the rate determines the answer. The negative capability list (no payments, no account changes, no external fetch, no input retention) reinforces rather than contradicts the annotations, though parts of it restate what the hints already say.

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?

Front-loaded with the user-question framing and the return values, with routing guidance before the negative list. Slightly padded by the four-item 'does not...' clause that partly duplicates the annotations.

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?

An output schema exists, annotations cover the safety profile, and schema documentation is complete, so the description only needed to add trigger, routing, precondition, and scope — all present. Nothing an agent needs to select or invoke it 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, but the description adds meaning the schema does not: monthlyPayment is contextualized as the fixed monthly figure driving the calculation, and aprPercent is escalated from 'omit when unknown' into a hard requirement for a meaningful result. It still does not clarify the cardName-vs-cards relationship or how minimum payment fallback interacts with monthlyPayment.

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?

Names a specific computation (months to clear a balance at a fixed monthly payment) and its second output (interest paid over that time), framing it with the exact user questions it answers. It explicitly distinguishes itself from get_reported_snapshot and simulate_paydown, so an agent can route without opening either schema.

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?

Opens with concrete trigger phrasings ('if I pay $200 a month, when is this paid off?', 'what happens if I only pay the minimum?') and states the exclusion plus the named alternatives for the excluded case. The 'cost question, not a reporting one' framing gives a clean decision rule.

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, closed-world behavior, and the description reinforces this by stating it does not make payments, change accounts, fetch external data, or retain inputs. It also discloses the dual-answer output and trade-off logic, adding useful context beyond the safety 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?

Three sentences, front-loaded with the trigger and output summary, followed by behavioral constraints. Every sentence carries distinct information with no waste.

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 tool has an output schema and full parameter coverage, so the description does not need to restate them. It still provides the missing conceptual context: the two competing answers, why they diverge, and the read-only calculation boundary. Nothing material is left ambiguous for an agent to call it correctly.

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

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 parameter meaning in detail. The description only refers generically to 'the amount given' and 'supplied figures,' adding no parameter-specific guidance beyond the structured 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: 'which card to put a purchase on,' and names the two outputs it returns (least utilization impact vs. cheapest to carry) plus the trade-off. This clearly distinguishes it from sibling explainer and simulator 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 gives a clear trigger: 'Use this when someone asks which card to put a purchase on.' It does not explicitly name when to prefer a sibling such as simulate_paydown, but the framing is a definitive routing signal for purchase-allocation questions.

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?

Annotations already cover read-only, idempotent, non-destructive, closed-world, but the description adds substantial non-structured context: graceful degradation to general closure/retention info when no card figures are supplied, a hypothetical paid-off closure model, and explicit statements that it makes no payments, changes no accounts, fetches no external data, and retains no inputs.

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?

Front-loads the trigger phrases an agent matches on, then layers the mode behavior. Dense but every sentence carries information; the closing 'does not make payments, change accounts, fetch external data, or retain tool inputs' slightly repeats the earlier non-mutation disclaimer.

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?

Output schema exists, so return shapes needn't be spelled out, and the description still explains what each input mode produces and what happens when optional data is omitted. For a read-only estimator with three optional parameters, nothing an agent needs to invoke it 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, but the description adds conditional semantics the schema can't express: cards alone yields a closure calculation, while cards plus cardName additionally yields before/after utilization, the limit leaving the denominator, and band-crossing detection. It also notes cardName is only meaningful alongside cards, which clarifies a real dependency.

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?

States a specific verb and resource — calculating/explaining the utilization impact of closing a card — and immediately bounds it: 'It does not close, cancel, or change any card; it only explains and calculates.' That separates it cleanly from mutating or payoff-simulation siblings like simulate_paydown and calculate_payoff_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?

Gives concrete user-question triggers ('should I cancel the credit card I never use', 'is it bad to close a card') and a scope of cancelling, downgrading, and consolidating. It also sets the no-data vs with-data usage modes. It stops short of naming a sibling alternative for overlapping questions (e.g. compare_cards_for_purchase or simulate_paydown), so it's clear context without explicit routing.

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 declare readOnly, idempotent, non-destructive, and closed-world, and the description is consistent with all of them. It adds real context beyond them: the tool returns bundled reference material (not live data), it distinguishes the Canadian rule from the American one, and it flags that the 30-day gap is often actionable. It does not describe response shape in detail, but an output schema exists to carry that.

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?

Front-loaded with the use case, then the concrete content of the answer. It is on the long side and the trailing "Returns bundled reference material..." sentence is somewhat generic, but no sentence is filler and the actionable 30-day insight is placed where it will be read.

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, the description need not enumerate return fields, and it instead conveys the substantive answer components (gap, scale, duration) plus the jurisdiction caveat. The only soft spot is that the optional daysPastDue input is left under-explained relative to how much the rest of the answer is spelled out.

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% and the single parameter already documents that daysPastDue changes which part of the answer leads. The description only gestures at this with "optionally filtered or calculated from inputs," adding no threshold guidance (e.g., what counts as 'nearly late'). Baseline 3 is correct when the schema does the heavy lifting.

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?

States a specific verb-and-resource: it explains what happens when a Canadian credit card payment is missed, including the 30-day reporting gap, the R1-R9 scale, and retention duration. This clearly separates it from siblings like explain_retention_periods and explain_when_issuers_report, and it pins the answer to the Canadian jurisdiction.

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?

"Use this for a missed, late, or nearly-late payment, or for 'how long will this hurt me'" gives an explicit triggering condition in the user's own phrasing. The closing clause rules out live-data and account-mutation use cases. It stops short of naming a specific sibling as the alternative for adjacent questions, which keeps it from 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the burden is low; the description still adds real context by saying durations vary by information type, bureau, and province, that source links are included, and that the material is bundled reference rather than live data. The only redundancy is 'does not change accounts,' which restates destructiveHint=false.

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?

Front-loads the usage trigger and keeps to four sentences with no filler. The repeated 'Returns…' openings are slightly mechanical and the closing negative clause mildly duplicates the annotations, but nothing is wasted space.

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?

An output schema exists, so return values need not be explained, and the description covers domain scope, variability, and sourcing. The only completeness gap is the unresolved 'filtered or calculated from inputs' wording against a parameterless 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?

With zero parameters, the baseline would be 4, but the phrase 'optionally filtered or calculated from inputs' implies inputs exist that the empty schema does not define. That mismatch leaves the agent unsure whether arguments are expected, so it lands below baseline.

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?

States a specific verb and resource ('Returns retention periods on a Canadian credit file') and enumerates the covered information types (closed accounts, late payments, collections, inquiries, bankruptcy, proposals, judgments). This clearly differentiates it from the narrower sibling explain_missed_payment and the broader 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?

Opens with an explicit trigger: 'Use this for any "how long will this stay on my credit report" question,' which tells the agent exactly which user intent routes here. It does not name a competing sibling or state exclusions in tool terms, 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 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?

Beyond the readOnly/idempotent annotations, the description discloses that nothing is looked up on any account, the estimate is pure arithmetic on the supplied date, no per-issuer table exists, and it returns bundled reference material rather than live data. That is substantive behavioral context an agent cannot get from the annotations alone.

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 usage condition is front-loaded, which is good, but the text contains redundancy: 'looks nothing up on any account' is repeated later as 'does not fetch live data or change accounts,' and 'Returns bundled reference material, optionally filtered or calculated from inputs' reads as boilerplate. Some flowery phrasing ('the one most people have never been shown') costs space without adding 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 an output schema available and annotations covering the safety profile, the description fills the remaining gaps: when to call it, what it does and does not look up, and how the due-date estimate is derived. Nothing essential for correct invocation 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 both parameters are already documented. The description still adds meaning by clarifying that supplying a due date produces a derived estimate via the 21-day grace-period rule, reinforcing why the parameter matters rather than just what it is.

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?

States a specific verb and resource: returns the ways to find the closing date of a Canadian credit card, and explains that the date is a dependency for other tools. However, it never names the obvious sibling (get_statement_calendar) or explains how this differs from it, so sibling differentiation is only implied.

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?

Explicit trigger conditions are given: 'whenever someone does not know their statement closing date, or gives a payment due date and asks what to pay.' There is no when-not-to-use guidance or named alternative, which keeps it from 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?

Annotations already declare read-only, non-destructive, idempotent, closed-world behavior. The description adds substantial context: the plan is text plus structured data, nothing is scheduled or executed, no payments or account changes occur, no external data is fetched, and inputs are not retained.

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?

Five sentences, front-loaded with the usage trigger and purpose, then output ordering, return format, and side-effect boundaries. Every sentence contributes useful information, with no 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?

Complete for a read-only planning tool: it states input dependency, output form, step ordering, and absence of side effects, and an output schema exists. It could better route against planning-adjacent siblings like simulate_paydown and calculate_payoff_timeline.

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 detailed per-field descriptions for goal, cards, today, and targetUtilization. The description adds little parameter-specific meaning beyond mentioning the three goals and that scenarios are calculated from supplied figures, so 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?

States a specific verb and resource: 'Returns an ordered plan' for 'credit plan' goals. It enumerates the three goals and distinguishes itself from single-action siblings with 'more than the next single action.'

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 sentence gives a clear trigger: use when someone wants more than the next single action. It does not explicitly name alternatives such as get_next_move or simulate_paydown, nor does it state when not to use this tool.

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 read-only and idempotent annotations, the description discloses important behavioral limits: the answer is bundled reference material, does not fetch live data or change accounts, and credit-import coverage is partial with several major source countries missing entirely. Those coverage caveats materially affect how an agent should present and trust the output.

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 front-loads the intended use case and the returned path before adding the coverage caveat and scope note. It is generally efficient, though the final sentence about bundled reference material and not fetching live data is somewhat boilerplate and could be integrated more tightly.

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 two fully described optional parameters, rich annotations, and an output schema, the description supplies enough context to call the tool correctly. Its main remaining gap is sibling routing: it does not clarify when to prefer this over related planning or mechanics tools, and it barely explains how monthsInCanada shapes the answer.

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 both parameters are already documented, setting a baseline of 3. The description adds that homeCountry specifically determines whether the credit-import route is open, but monthsInCanada is only indirectly implied by the phase language and gets no additional detail.

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 — it returns the ordered path for building a Canadian credit file as a newcomer — and enumerates the phases covered (before SIN, credit import, first tradeline, accumulation). This makes it clearly distinguishable from mechanics explainers like explain_canadian_credit_mechanics and from product lists like list_credit_building_products.

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 an explicit trigger audience — immigrants, newcomers, international students, temporary residents — and says to supply the home country for a specific import answer. However, it does not name sibling tools or clarify boundaries against related tools such as get_credit_plan, explain_canadian_credit_mechanics, or list_credit_building_products, leaving some selection ambiguity.

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 cover read-only, idempotent, non-destructive, closed-world, so the description isn't carrying the safety burden. It still adds real value beyond them: it clarifies the tool is a pure calculation over supplied figures, makes no payments or account changes, fetches no external data, and retains no tool inputs — the last two being non-obvious data-handling 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?

Front-loaded with the user-intent trigger, then outputs, then boundaries. Slightly redundant: 'It does not determine future bureau-reported balances' and 'This is the difference between today's balance and the figure the issuer transmits' say nearly the same thing, costing a sentence.

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 pure calculation tool with a full schema, complete annotations, and an output schema, the description covers purpose, inputs, and side-effect boundaries adequately. Return shape needs no explanation given the output schema. Only minor gap is not naming the sibling to use for bureau-reporting timing questions.

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 the per-field docs (APR vs unknown, creditLimit 0 for charge cards, statementCloseDate semantics) are thorough, so the schema does the heavy lifting. The description only restates 'supplied balances' and 'supplied closing date' without adding format or default guidance. 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 states a specific verb and resource — it computes utilization from supplied balances, days to the supplied closing date, and a hypothetical payment to hit a target. It also draws a boundary against the sibling concept of bureau-reported balances (e.g., explain_when_issuers_report). It stops short of naming an actual sibling tool, so disambiguation is by concept rather than by name.

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 concrete trigger language tied to user intent ('asks how their cards look, where they stand, or which card is the problem') plus an exclusion ('does not determine future bureau-reported balances'). No alternative tool is named, so the agent must still map the intent-to-sibling call itself.

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 cover read-only, idempotent, closed-world and non-destructive, so the description only needs to add context — and it does: it calculates from supplied figures, fetches nothing external, and explicitly retains no tool inputs. That privacy/no-retention note is genuine value 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 usage trigger is front-loaded in the first clause, followed by the return shape ordered as it will be returned, then a compact exclusion list. No sentence is filler and nothing is buried.

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, the description need not explain return values, and it still summarizes the ordering of events. Combined with exhaustive parameter docs, an agent has enough to call it correctly; only the count/today defaults are left entirely to the 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?

Schema coverage is 100%, so cards/count/today are all fully documented in the schema, and the baseline is 3. The description adds only the vague phrase 'calculates scenarios from supplied figures' without clarifying count, today, or the date-driven inputs beyond what the schema says.

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?

States a specific verb and resource: returns upcoming statement dates in order (pay date, close date, due date), and frames it around the closing-vs-due distinction. It does not explicitly name which sibling to prefer (e.g. find_statement_close_date), but the calendar-ordering purpose is unmistakable.

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?

Gives concrete trigger conditions: 'when someone asks about timing, what is coming up, or why the closing date differs from the due date.' It also lists what the tool does not do (no payments, no account changes, no external fetch), which steers the agent away from misuse, though it never names an alternative sibling tool.

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 bar is lower; the description still adds real context — content is bundled static reference material, not live data, and outputs are grouped by tier with bureau coverage. The warning about single-bureau (Equifax-only) reporting is domain value rather than tool behavior, but the 'confirm with provider' staleness caveat is genuinely useful.

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?

Front-loaded with the action and the non-live-data scope, which is good. But the middle sentences drift into product education (single-bureau reporting, upfront-fee warning signs) and the closing sentence 'Returns bundled reference material, optionally filtered or calculated from inputs' is generic filler that could be cut.

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 and full annotation coverage, the description only needs to establish scope and caveats, which it does: static reference data, provider terms may change, tier grouping. Nothing an agent needs to invoke correctly is missing, though the parameter story is thin.

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?

One optional parameter at 100% schema coverage, so the schema already documents the enum. The description only alludes vaguely to results being 'optionally filtered or calculated from inputs' and never names the tier filter or its values, adding little beyond the schema. 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?

Specific verb and resource: 'retrieve dated reference examples of Canadian secured cards and credit-building products.' The scope (reference catalogue, grouped by credibility tier, with bureau reporting) is concrete enough to distinguish it from the explain_*/simulate_* siblings, but it never names a sibling directly.

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?

'Use this to retrieve...' plus 'Confirm current terms and reporting arrangements with the provider' and 'does not fetch live data or change accounts' effectively describes the when (lookup/research) and the when-not (live account data). No sibling tool is named as an alternative, so it falls short of a 5.

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

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.