MTG Tools — Commander deck review and mana bases

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

Beyond annotations (readOnly, non-destructive), it adds critical behavioral context: 'Preview only: no saved build, email, purchase, or cart modification'; 'USD budget minimum remains $20; it is a spending cap, not a target'; and 'Shopping imports match by card name; printing and final prices may differ.' It also instructs the agent to always show warnings rather than misrepresenting a deficient build.

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 every sentence carries actionable information—budget semantics, mode selection, preview-only scope, price caveat, and warning handling. It is dense but not bloated.

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 10 parameters, no output schema, and preview-only behavior, the description covers the return contents ('card quantities, reasoning, prices, coverage, warnings, and shopping links') and the key behavioral risks. It does not elaborate on bracket or acceleration semantics, but the schema and annotations fill most remaining gaps.

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 only 40%, so the description must compensate. It usefully explains ownedLands, lockedLands, currentLands, and maxChanges, and clarifies budget cap semantics, but it leaves bracket, landCount, includeAcceleration, excludedCards, and commanderName mostly to bare schema types.

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 precise verb and resource: 'Generate 30–42 lands for a Commander within a USD purchase budget, optionally with acceleration.' It clearly distinguishes the tool from siblings that change brackets, reduce cost, repair decks, search commanders, or upgrade precons.

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 names three concrete usage modes: ownedLands to buy only missing copies, lockedLands to keep specific lands, and currentLands with maxChanges for a limited upgrade. It does not explicitly contrast with sibling tools, but the mode-based guidance is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful beyond-schema context: provider access can fail, nothing is purchased or saved publicly, warnings must be shown and the player chooses swaps, and bracket analysis is guidance not certification. This is solid added context, though return-format details are only lightly touched.

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?

Dense but front-loaded: the core action and accepted input forms come first, then constraints, then output expectations. Every sentence carries information, though the paragraph is long and could be broken up for scannability.

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

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

With no output schema, the description carries the return-value burden and does so well (cuts/additions, role counts, warnings, estimated cost, card links, TCGplayer cartUrl). Combined with the safety context, it is complete enough to call correctly, with only minor gaps around 'bracket' and 'maxChanges' semantics.

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 low (22%), so the description does meaningful compensating: it explains deck, commander, budget as USD, replaceCard restriction to one non-protected card, owned entry/copy limits, and locked/excluded as newline-separated names. It still leaves 'bracket' (the 1-5 target) and 'maxChanges' unexplained, so it does not fully close the gap.

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+resource ('Review a Commander bracket transition using bracketshift') and distinguishes the operation from the sibling set implicitly. It does not explicitly name any sibling tool to contrast with, so it lands at 4 rather than 5.

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?

Provides concrete input guidance (decklist or HTTPS Moxfield/Archidekt URL, fallback to plain-text export on provider failure) and the replaceCard narrowing behavior. However, there is no explicit when-to-use-this-vs-siblings guidance (e.g. vs find_replacements or reduce_deck_cost), leaving tool selection to inference.

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 safety (readOnly, non-destructive, openWorld, non-idempotent), so the description's credit is for adding real context: at most one proposal, possible empty result, heuristics are not functional equivalence, and an affiliate purchase summary is surfaced. These are qualities the annotations do not convey. It doesn't mention latency, rate limits, or what a warning/tradeoff payload looks like.

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?

Inputs are front-loaded in the first sentence and no sentence is purely filler; the affiliate disclosure and heuristic caveat each carry information. The prose is dense and run-on, stacking safeguards into a bare list rather than structured clauses, which slightly hurts scanability.

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 9-parameter, no-output-schema tool, the description covers the core contract, safeguards and null-result case, but leaves maxChanges undefined, gives no sense of how tradeoffs/warnings are returned, and doesn't reconcile the one-replacement promise with the multi-change parameter. Adequate to call correctly in the common case, incomplete at the edges.

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 only 22%, so the description must carry weight; it does partially by naming the guardrail inputs (budget, owned, locked, excluded, bracket) and clarifying that deck accepts a decklist or public HTTPS URL. But it never explains maxChanges, budgetUsd units/default, or bracket values, and 'at most one replacement' sits uneasily beside a maxChanges parameter bounded 1-15 with default 5, leaving the agent unsure how they interact.

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 first sentence states a specific verb and resource: given a decklist/URL, commander and replaceCard, propose at most one comparable-role replacement. That is far more precise than the title and clearly separates it from siblings like upgrade_precon or reduce_deck_cost, which operate on whole decks rather than a targeted single-card swap. It stops short of naming a sibling alternative explicitly.

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?

Prerequisites are clear ('complete Commander decklist or public deck URL', 'requested cut must be in the deck and cannot be the commander or protected'), and 'Can return no safe swap' warns of a null outcome. However, no sibling tool is named as an alternative for deck-wide optimization (e.g. repair_deck, reduce_deck_cost), so the agent must infer when to prefer 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?

Annotations already declare read-only, open-world, non-destructive; the description adds substantive context beyond them: no credentials or query parameters, sideboards and Moxfield companions excluded, no private access, and no saved server copy. It also discloses the return shape (quantity-prefixed main-deck text, tagged commander, card count, warnings), which no output schema provides.

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 source, followed by scope, exclusions, and recovery. Every sentence carries information, but the density makes it read as a run-on list and the *CMDR* fallback instruction sits awkwardly at the end.

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?

Covers input format, output shape, exclusions, error handling, and the recommended next step — everything an agent needs to call this correctly. The only minor omission is that idempotentHint=false (repeated fetches may see changed decks) goes unmentioned, but nothing critical 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?

With one parameter at 0% schema coverage, the description carries the burden and does so well: it specifies the URL must be public HTTPS, from Moxfield or Archidekt, and free of query parameters. It does not mention the 500-character limit or URL syntax edge cases, so it falls short of full compensation.

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 ('Read a public HTTPS Moxfield or Archidekt deck URL') and names the supported sources. It is unmistakable against siblings like build_mana_base or repair_deck, which transform decks rather than ingest them from a URL.

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?

Explicitly routes the agent forward ('Follow with a deck-review tool to validate names and legality') and handles the failure case ('If Moxfield access is blocked, do not repeat the URL request'), including a concrete fallback of asking the user for Download > Copy Plain Text with *CMDR* marking. This is when/when-not guidance with alternatives, not implicit usage.

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?

With annotations already declaring readOnly/openWorld, the description still adds real behavior: URL imports silently exclude sideboards and Moxfield companions, provider access can fail, nothing is purchased or saved publicly, and bracket analysis is 'guidance, not certification'. It also describes return content (cuts/additions, role counts, warnings, cost, TCGplayer cartUrl), which matters since no output schema exists.

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 purpose and input rules, but the body is a dense stream of clauses crammed into run-on sentences that mix parameters, failure modes, and output description without structure. Most sentences carry information, yet the packaging hurts scannability.

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 9-parameter tool with 22% schema coverage and no output schema, the description covers inputs, failure handling, return contents, and side-effect guarantees. The remaining gaps are the unexplained bracket and maxChanges parameters, which materially shape the output.

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 only 22%, but the description compensates for some gaps: replaceCard's limiting semantics, budget in USD, owned's 150-entry/100-copy limits, and that locked/excluded are newline-separated card names. It says nothing about bracket (1-5, default 3) or maxChanges, which remain undocumented in both places.

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: 'Find lower-cost deck replacements using budgetswap', with scope clarified (single card via replaceCard, full deck otherwise). It does not differentiate itself from the sibling find_replacements, which sounds like the closest alternative, so an agent must guess between them.

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 input requirements (full quantity-prefixed list including commander, or public HTTPS Moxfield/Archidekt URL), an explicit recovery path when provider access fails ('request a plain-text export'), and a downstream instruction ('let the player choose swaps'). It never names when to prefer a sibling tool such as find_replacements or upgrade_precon instead.

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/openWorld annotations, it discloses that nothing is purchased or saved publicly, that URL imports exclude sideboards and Moxfield companions, that budget is in USD, and that bracket analysis is guidance rather than certification. It does not explain why a read-only tool is marked non-idempotent (presumably price/stock drift), which is the one behavioral gap.

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 purpose, then input forms, then outputs, then caveats — a sensible order. Nearly every sentence adds operational detail, though the owned/locked/excluded sentence is dense and slightly reads as schema restatement.

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

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

With no output schema, the description properly enumerates the return payload (proposed swaps, role counts, warnings, estimated cost, card links, cartUrl) and flags external-provider failure modes. Only the maxChanges parameter and the exact bracket semantics are left for the agent to guess.

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 only 22% schema coverage, the description carries the parameter burden and does: it defines the deck input forms, the replaceCard restriction (single non-protected card), owned as quantity-prefixed up to 150 entries/100 copies each, and locked/excluded as newline-separated names. maxChanges, bracket range, and the required-vs-embedded nature of commander are left unaddressed.

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 concrete verb and resource — repair deck roles and consistency from a decklist or URL — and enumerates what comes back (cuts/additions, role counts, warnings, cost, cartUrl). It never names the nearest sibling (find_replacements, upgrade_precon, reduce_deck_cost), so the agent must infer boundaries, but the described output profile is distinctive enough to be recognizable.

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 real usage conditions: accept either a full quantity-prefixed list with commander or a public HTTPS Moxfield/Archidekt URL, and if provider access fails ask for a plain-text export. It also tells the agent to show all warnings and let the player choose swaps. It stops short of explicit 'use X instead of Y' routing against siblings.

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 establish readOnly, openWorld, non-idempotent, and non-destructive behavior. The description adds useful non-annotation context: result cap, Oracle text, null prices, affiliate links, disclosure requirements, search boundedness, and 'No purchases.' It does not discuss error behavior or rate limits, but it is substantially more transparent than 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 description is dense and front-loaded: purpose first, then optional filters, color semantics, return shape, and behavioral cautions. Every sentence earns its place, 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?

With no output schema, the description does a good job explaining return fields (Oracle text, prices, source, optional affiliate links) and result count. It covers all four parameters semantically and adds important behavioral caveats. Minor gaps remain around sorting, pagination, and error behavior, but nothing critical is missing for a bounded search 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?

Schema description coverage is 0%, so the description carries the burden and largely succeeds. It explains query syntax ('Scryfall syntax'), color semantics ('C or blank colors means colorless only; omit colors for any identity'), price-cap meaning, and result count up to 20, which maps to the limit parameter. It does not spell out the limit default or range, but that is already in the schema.

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

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

The description states a specific verb and resource: 'Search card names or Scryfall syntax.' That clearly scopes it as a card-search tool, distinct from deck-manipulation siblings like import_deck or repair_deck. It does not explicitly distinguish itself from search_commanders, so it falls short of full sibling 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?

Usage is implied by 'Search card names or Scryfall syntax' and the color/price-cap options, but the description never says when to choose this over search_commanders or find_replacements. The 'bounded and not an exhaustive recommendation' note adds context but not selection 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds genuine value by warning that the autocomplete may return non-commander cards and that only the primary field is validated, which tells the agent to distrust secondary results.

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 tight sentences with the core purpose front-loaded and the caveat followed by the downstream hint. The phrase "only the primary field is validated as a supported Commander choice" is slightly convoluted but earns its place as a warning.

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

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

For a single-parameter, read-only search with no output schema, the description covers purpose, result-quality caveat, and intended downstream use. It could still note result limits or matching behavior, but nothing essential to a correct call 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 0% for the single query parameter, so the description must carry the weight. It conveys that the query is a name and recommends an exact name, but says nothing about length bounds, fuzzy matching, or how partial names behave — leaving the parameter only partly characterized.

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 ("Find Commander candidates by name") that an agent can immediately distinguish from the sibling search_cards tool. It doesn't explicitly name search_cards as the alternative, which keeps it short of a 5.

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 implies when the tool applies (finding a commander before build_mana_base) and adds the constraint to use the exact commander name for that downstream call. However, it never contrasts this with search_cards or states when not to use it, so usage is only implied rather than spelled out.

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 (readOnlyHint/destructiveHint), the description adds critical behavioral context: it guarantees that 'Nothing is purchased or saved publicly' (security/persistence) and details the limitations of the analysis ('Bracket analysis is guidance, not certification').

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 lengthy due to the tool's complexity, but it is perfectly structured. It front-loads the inputs, details the process/constraints, and concludes with outputs and safety guarantees, ensuring the agent flows logically from invocation to expected result.

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?

Since no output schema is present, the description is exceptionally complete by explicitly listing every return element: 'proposed cuts/additions, role counts, warnings, estimated cost, individual card links and a TCGplayer cartUrl'. It leaves no ambiguity about what the agent can expect to receive.

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 description coverage is only 22%, yet the description compensates heavily by detailing the required formats for complex fields like `deck` (quantity-prefixed list or URL) and `owned` (up to 150 entries with specific quantity formats). This makes the low coverage tolerable by providing all necessary structural information.

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's function: 'Upgrade a Commander precon.' It clearly defines the input mechanisms (URL vs. plain list) and the nature of the output (proposals and estimated costs), distinguishing it as a comprehensive optimization tool.

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

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

It provides highly specific operational guidelines, such as noting that URL imports exclude sideboards/companions, and instructing the agent to request a plain-text export if provider access fails. It also manages user expectations regarding the output quality ('Bracket analysis is guidance, not certification').

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