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

Beyond the annotations, the description adds the significant detail that removal occurs in the OS keychain and leaves the env var untouched. This is meaningful context for a mutating operation, though it does not describe edge cases such as removing a non-existent key; the idempotentHint covers the repeat-safety aspect.

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?

One sentence immediately states the action, target, and scope. Every phrase earns its place, and the parenthetical about the env var is compact but valuable.

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 parameterless tool with an output schema and annotations already present, the description is complete. It tells the agent what will be changed, where, and what will not be affected, leaving no missing information needed 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 tool takes no parameters, so schema coverage is trivially 100% and there is no parameter behavior to describe. The baseline of 4 applies because no parameter semantics are needed.

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 ('remove') and names the exact resource ('stored YNAB API key from the OS keychain'). It also clarifies that the env var is unaffected, which distinguishes it from related credential tools like set_api_key.

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?

Clear scope is provided: only the keychain-stored key is targeted, and the env var remains intact, which implies when to use this tool versus env-var-based configuration. It does not explicitly name alternatives or exclusion conditions, but the context is sufficient for a zero-parameter 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 destructiveHint annotation, the description discloses that mutating calls are gated by a preference, must use the ynab.write.* namespace, and have an eval dry-run exception. It also explains the execution model: snippets are treated as the body of an async function with await and return. This adds substantial behavioral context beyond the annotations.

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

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

The description is dense but efficient: three sentences convey purpose, authorization requirements, mutation constraints, and the async execution model. It front-loads the core purpose and uses code formatting for the example, 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?

Given the lack of an output schema and empty parameter descriptions, the description covers the most important operational details: what the snippet runs against, mutation gating, and async assumptions. It does not explain the timeout parameter, dry-run mode specifics, or return behavior, so it is strong but not fully complete.

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

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

The description adds meaningful semantics for the required 'code' parameter by explaining that the snippet becomes the body of an async function and showing example usage. However, schema description coverage is 0%, and the optional 'timeout' parameter is completely undocumented in both the schema and the description. This is a partial but incomplete compensation for the schema 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?

The description clearly states a specific verb and resource: 'Execute a Python snippet against the gated ynab.read/ynab.write Code Mode API.' This distinguishes the tool from its sibling tools, none of which perform code execution, despite the otherwise generic name 'execute.'

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

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

The description gives clear context on when the tool can be used: it is enabled by default, and mutating calls require the code_mode_mutations_enabled preference and must use ynab.write.*. It does not explicitly name alternative tools or list when not to use it, so it falls short of a 5, but the constraints are concrete and actionable.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: it reads from the in-memory ynab_resources.preferences, reflects the env > preferences.json > defaults precedence, and returns a markdown table. It also mentions the equivalent resource endpoint, giving agents a fuller understanding of side-effect-free behavior.

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

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

The description is three focused sentences with the primary purpose front-loaded. Each sentence adds distinct value: the action and output format, the underlying data source and precedence, and the alternative resource access. There is no redundancy or filler.

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

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

For a zero-parameter, read-only tool with an output schema, the description is fully complete. It explains where the data comes from, how it is formatted, and provides an alternative access method, leaving nothing essential 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 tool has zero parameters, and the input schema is fully covered, so per the rubric the baseline is 4. The description does not need to explain parameters, and it provides no misleading parameter-related 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 opens with a specific verb and resource: 'Return the current YNAB MCP preferences as a markdown table.' It clearly identifies the tool's output format and distinguishes it from sibling write tools like set_preference by emphasizing a read operation.

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

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

The description gives clear context on when to use the tool: whenever current preferences are needed, and it notes that the same content is available as a resource for clients that prefer that access path. It does not explicitly state when not to use it relative to siblings, but the read-only framing and resource alternative provide adequate 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 readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by stating that the call fetches the current user id and does not touch budget data, which helps an agent understand side-effect scope.

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

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

Two sentences with no filler, and the core action is front-loaded. Every clause earns its place by adding purpose or exclusion context.

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-argument read-only auth-check tool with an output schema and safety annotations, this description is fully sufficient. 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?

The tool takes zero parameters, so the schema's empty properties object fully documents the input contract. The description appropriately focuses on output behavior rather than inventing parameters. Baseline 4 applies per the zero-parameter rule.

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 'Verify' and resource 'YNAB API auth' and defines the operational result ('fetching the current user's id'). It clearly distinguishes itself from budget-touching siblings by saying it leaves budget data alone.

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 identifies the use case: confirming YNAB_API_KEY is set and valid. It also gives an exclusion ('without touching budget data'), which guides an agent away from heavier tools. However, it doesn't name a specific alternative tool, so it gets slightly less than a perfect 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 readOnlyHint/idempotentHint annotations, it discloses sandbox execution, the exact shape of the spec variable, the absence of live YNAB API access, and the return shape (same CodeModeResult as execute). This is rich, non-redundant behavioral context.

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?

Purpose, environment, data shape, example, and caveat are all conveyed in a compact, front-loaded description. No sentence is 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 single-parameter tool with no output schema, the description provides the spec keys, sandbox boundary, no-live-access disclaimer, and return shape reference. It is slightly dependent on the agent knowing what CodeModeResult looks like, but that is a minor gap given the example and sibling context.

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 0% schema description coverage, the description largely compensates: 'code' is implied to be the Python snippet, and the example clarifies the expected form. It could be more explicit that the code must be a return expression and what happens on invalid input, but it is sufficient for correct use.

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 ('Discover') and resource ('available YNAB tools') by running a Python snippet against the tool catalog. It clearly separates this from live API operations by noting 'No live YNAB API access' and references execute only for return-shape comparison.

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 makes the use case explicit: introspect/filter the tool catalog. It also gives an exclusion ('No live YNAB API access') and an example of how to query the spec. It does not explicitly enumerate when-not-to-use relative to siblings like execute or ping, so not 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 annotations, the description discloses the specific keychain storage mechanism, the service/user identifiers, and the fallback precedence of the YNAB_API_KEY env var. These are useful behavioral details that annotations alone do not provide. It does not state whether an existing stored token is overwritten, but idempotentHint: true partially mitigates that 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?

The description is front-loaded with a one-sentence purpose statement, followed by a focused, information-dense elaboration. Every sentence contributes either storage details or resolution behavior; there is no 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?

For a simple one-parameter setter, the description covers what an agent needs: what to pass, where the value is stored, how it is picked up later, and the env-var precedence caveat. The presence of an output schema reduces the need to document return values, and the operational behavior is fully described.

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 must carry the semantic weight for the single api_key parameter. The first sentence explicitly identifies it as a YNAB personal access token, adding meaning beyond the schema's bare 'Api Key' title. It does not specify formatting or validation expectations, but the mapping is clear and sufficient for a single string parameter.

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 verb and resource: 'Store a YNAB personal access token in the OS keychain.' This unambiguously states the tool's function and is clearly distinct from siblings like clear_api_key or ping.

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

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

The description gives clear context for when the tool matters by explaining that the key persists for future requests and runs. It also provides a key caveat: the YNAB_API_KEY env var still wins if set, which implicitly tells agents when the tool will have effect. However, it does not explicitly name or contrast sibling tools such as clear_api_key.

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 idempotentHint annotation, the description reveals important runtime behavior: persistence to a JSON file, accepted boolean representations, empty-string clearing semantics for default_budget_id, and the coercion error that occurs on non-optional fields. These are exactly the behavioral details an agent needs and cannot infer from 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 well-structured and front-loaded: purpose first, then validation rules, then edge-case behavior, then a sibling-equivalence note. Every sentence contributes necessary 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?

Given that there is an output schema to cover return values, the description provides enough context for correct invocation: permitted names, coercion rules, and clearing behavior. It is only slightly incomplete on the exact value representation for the numeric TTL preference.

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%, so the description carries the parameter burden and does so well: it defines valid values for name, documents boolean coercion formats for value, and explains the special empty-string case. A small gap remains because the expected format for category_cache_ttl_minutes (e.g., integer string) is not explicitly stated.

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 verb and resource: "Set a single preference and persist it to preferences.json." It then enumerates the exact valid field names, which makes the tool's scope unambiguous and distinguishes it from siblings like execute or get_preferences.

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 implies this tool is for setting named preference fields one at a time, and adds an explicit equivalence note: changes to default_budget_id are the same as calling set_preferred_budget_id. It does not spell out when not to use the tool, but the sibling differentiation is strong enough for an agent to route 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?

Annotations already provide idempotentHint=true, and the description does not add further behavioral details. It adequately indicates a write operation but lacks depth on side effects or persistence.

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 sentence of 6 words, front-loading the action and resource with no wasted words.

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 simplicity of the tool (one parameter, output schema present), the description is minimally adequate but could improve by clarifying the effect, e.g., that it sets a default for subsequent operations.

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 0% schema description coverage, the description compensates by naming the parameter as a 'YNAB budget ID', but does not explain format or source, leaving ambiguity.

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 action ('Set') and the resource ('preferred YNAB budget ID'), distinguishing it from sibling tools like set_api_key and set_preference.

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

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

No guidance is provided on when to use this tool versus alternatives, or any prerequisites such as needing to have a valid budget ID beforehand.

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