ToolRouter

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that, explaining the different output shapes for the two invocation modes and listing what the detail view includes. It does not contradict 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 compact, front-loaded with the tool's core purpose, and every sentence earns its place. It conveys both modes and the detail contents without fluff or redundancy.

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 tool with one optional parameter, rich safety annotations, and no output schema, the description is complete enough. It tells the agent what happens in each mode and what the detail view contains, so nothing essential is missing for correct invocation.

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

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

The schema already documents the slug parameter at 100% coverage, so the baseline is 3. The description adds value by clarifying the conditional effect of omitting versus providing the slug, turning a bare schema parameter into a clear behavioral choice.

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 and resource ('List all billing contexts') and clearly defines two modes: a summary list without a slug and a full detail view with a slug. This distinguishes it from sibling tools like account_preferences and account_switch by focusing on account/team listing and billing context inspection.

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 a clear decision rule: omit slug for a summary list, provide slug for full detail. It does not explicitly state when not to use this tool or mention alternatives, but the mode-based guidance is strong enough for an agent to invoke it 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 indicate the tool is not read-only, not destructive, and idempotent; the description's read/write framing is consistent with those annotations. However, it adds little beyond the action contract and does not disclose effects of setting values or any operational constraints.

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 two sentences with no filler. It front-loads the core purpose and immediately gives the action routing, making it easy for an agent to parse and act on.

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

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

For a read/write preferences tool, the description plus schema and annotations cover the essentials: what it manages, how to choose the action, and the fields involved. The lack of an output schema is mitigated by the clear 'get' read semantics, though details about the return format are not stated.

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

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

Schema coverage is 100%, with every parameter already documented including set-only usage and constraints. The description adds only a high-level action/field relationship, which is helpful but not necessary given the schema's completeness.

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 reads or writes billing preferences and names the key pref fields (auto-reload, budget cap, default context). It is specific about the resource and operation, though it does not explicitly distinguish itself from sibling tools like account_setup or account_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 gives direct action guidance: use 'get' to read and 'set' with fields to write. This is clear context for choosing the correct invocation, but it does not mention when to prefer a sibling tool or 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?

The description says the tool will 'initialize' or 'provision' the account, implying mutating side effects, while annotations declare readOnlyHint=true. This is a direct contradiction: an agent cannot trust whether this operation changes state. Beyond that, the description does not clarify whether provisioning persists anything.

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 the key directive 'CALL THIS FIRST' front-loaded and no filler. Every clause earns its place by either stating the action, trigger conditions, or return value.

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 tool, the description covers when to call, what it does, and what it returns. However, the contradiction between 'provision' and readOnlyHint leaves the side-effect model unclear, and with no output schema the agent is left without a reliable expectation of the response shape.

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?

There are zero parameters, so the empty schema is fully self-describing and there is no parameter documentation burden. The description adds no parameter detail, which is appropriate for a parameterless tool.

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 verb ('Initialize or re-check'), a clear resource ('your account'), and a concrete return value ('user ID and plan'). The 'CALL THIS FIRST' instruction and the listed user intents distinguish it from siblings like account_list and account_switch.

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 call the tool: when the user asks to set up ToolRouter, connect their account, check account status, or get started. It does not explicitly name alternatives or exclusions, but the 'CALL THIS FIRST' guidance provides clear context.

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

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

Annotations already cover mutation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds that this switches the 'billing context' and accepts slugs or team IDs, but does not disclose additional behavioral details such as persistence, side effects, or error conditions. 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?

A single, well-structured sentence that leads with the action and resource, then provides relevant examples. No filler or redundant content.

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 tool with full schema coverage and annotations describing idempotency and non-destructiveness, the description is largely complete. It could mention expected return behavior or prerequisites, but these are minor gaps for a switch operation.

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 fully documents the single 'context' parameter. The description essentially restates the same parameter details ('slug', 'team ID') without adding new semantic meaning beyond what the schema already provides.

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 ('Set') and a specific resource ('active billing context'), making it clear what the tool does. It also gives concrete identifier formats (slug or team ID), which helps distinguish it from account_list and account_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 when to use the tool—when the agent needs to change the active billing context—but it does not explicitly mention alternatives or exclusions. There is no explicit guidance such as 'use account_list to enumerate available accounts before switching.'

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

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

The description adds a meaningful behavioral side effect beyond the annotations: 'Knowledge you add here will be available to all future tool calls.' It also explains the retrieval-benefit framing of the MemPalace hierarchy, giving the agent a useful mental model of persistence and organization.

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 two sentences with no filler: the first front-loads the action, and the second adds the key consequence and optional organization. Every clause earns its place.

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

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

For an 8-parameter create tool with 100% schema coverage, the description covers the core effect, persistence across future calls, and the purpose of the optional hierarchy. It does not discuss return values or duplicate handling, but the absence of an output schema and the rich input schema make this adequate.

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

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

Schema coverage is 100%, so the schema already documents every parameter, which would normally justify a baseline of 3. However, the description adds semantic value by grouping wing/room/hall into a hierarchy and explaining their benefit for 'sharper retrieval', which goes slightly beyond the schema's individual property descriptions.

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 'Create a new brain page' with a specific verb and resource, and clearly distinguishes this from sibling operations like brain_update or brain_delete. The optional wing/room/hall hierarchy is mentioned without muddying the core purpose.

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 clear this tool is for adding new knowledge, and the sentence about future tool calls signals why an agent would choose it over a query or update tool. It does not explicitly name alternatives or when-not-to-use conditions, 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?

All annotations are false, so the description carries the full burden of behavioral disclosure. It does mention the team_sleep lifecycle and its admin requirement, but it does not explain the side effects or risks of link, promote, lint, or rebuild_index, whether operations are reversible, or what success/failure looks like. This is a significant gap for a mutating admin tool.

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

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

The description is compact and front-loaded: scope, action list, then team_sleep-specific instructions. Each sentence contributes useful information without filler. The team_sleep sentence is longer than the others, but that complexity is inherent to the subcommand structure.

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?

This is an eight-parameter administrative tool with no output schema and no informative annotations, yet the description only fully explains the team_sleep branch. The semantics, side effects, and result behavior for link, promote, lint, and rebuild_index are left almost entirely to parameter names and schema descriptions. That is insufficient for safe and correct use of the non-team_sleep actions.

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

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

Schema description coverage is 100%, and every parameter already has a meaningful description and enum where appropriate. The description adds useful cross-parameter context for team_sleep (sub_action values, optional timezone, default UTC, 3 AM behavior), but much of that is also present in the schema, so the value added is incremental rather than transformative.

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 an administrative resource ('Brain admin operations') and enumerates five specific executable actions: lint, link, promote, rebuild_index, team_sleep. This goes well beyond a tautology and tells an agent what the tool can do, though it does not explicitly distinguish the tool from siblings like brain_lint or brain_settings.

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 explicit usage guidance for the team_sleep subcommand: which sub_action values to pass, that timezone is optional, and that a team admin role is required. However, it gives no guidance on when to prefer brain_admin over the dedicated sibling tools, nor when individual actions like link vs promote vs rebuild_index should be chosen.

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

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

The description adds a concrete behavioral consequence beyond the annotation destructiveHint=true: the page stops appearing in searches and tool consultations. It does not state whether archiving is reversible or whether associated content is removed, but the annotations already establish the destructive and idempotent nature.

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

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

Two short sentences, front-loaded with the action and followed by the relevant consequence. Every word earns its place with no filler or repetition of the schema.

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

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

For a single-required-parameter tool with no output schema, the description plus schema gives enough to invoke correctly. A brief note on reversibility or confirmation would make it fully complete, but annotations already signal that this is a destructive operation.

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 page_id parameter is already documented with its bp_... format. The description adds no parameter-specific meaning, so it rests on the schema, which is the baseline expectation.

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 ('Archive') with a clear resource ('a brain page') and states the operational consequence: it will no longer appear in searches or tool consultations. This clearly distinguishes the tool from siblings like brain_update or brain_query.

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 described effect implies this tool is for removing a brain page from active use, but there is no explicit 'use this when...' guidance and no mention of alternatives or when not to use it. The context is understandable but left 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses that output is redacted for credentials, that a 404 is returned when no drawer is linked, and that drawers are a Step 4 feature for allowlisted tools only. This gives the agent actionable success and failure 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 core action is front-loaded in the opening sentence, and each subsequent sentence adds distinct value: one explains when to use it, the other describes the edge case. There is no redundant or filler content.

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 tool with no output schema, the description covers return semantics (verbatim source text, redacted), the 404 error case, and availability restrictions. An agent has sufficient information to decide whether to use it and what to expect.

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 fully describes page_id ('Brain page ID (bp_...) whose drawer to expand') with 100% coverage, so the description adds no additional parameter-specific guidance. The description's mention of 'linked from a brain page' recontextualizes the parameter without adding new constraints.

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 ('Retrieve') and resource ('verbatim source text (a 'drawer') linked from a brain page'), clearly distinguishing it from siblings like brain_query or brain_status. The title reinforces this with 'reveal raw source'.

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 provides a use condition: 'Use this when a summary lacks specifics you need.' It also warns of a 404 when no drawer exists, implicitly suggesting when not to use it, but it does not name an alternative 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by specifying what the checks detect (stale pages, orphaned knowledge), but no deeper behavioral traits like output format or whether fixes are applied. This is adequate but not exceptional.

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 concise sentence that front-loads the main action ('Run maintenance checks') and then elaborates with specific examples. No filler, no repetition of schema or 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?

For a zero-parameter, non-destructive tool with rich annotations, the description provides enough context about its purpose and typical findings. The absence of an output schema is not a major gap because the described behavior (finding issues) implies a list or report, which is sufficient for invoking the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add. Baseline 4 applies for zero-parameter tools; the description is not required to explain any arguments.

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 ('run') and a clear resource ('your brain'), then specifies concrete outcomes: 'find stale pages, orphaned knowledge, and other issues.' This clearly distinguishes it from sibling tools like brain_query or brain_add, which operate differently.

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

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

The description implies when to use the tool—whenever maintenance or health checks on the brain knowledge base are needed—and names the kind of issues found. However, it does not explicitly mention when not to use it or compare it to alternatives such as brain_status or brain_query, leaving some routing 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 declare readOnly, idempotent, and non-destructive behavior, so the description's main job is to add behavioral context. It adds 'returns pages ranked by relevance' and the narrowing semantics, but it does not disclose details such as the shape of returned pages or how temporal as_of results behave beyond what the schema already states.

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 two sentences with no wasted words: the first states the purpose and result, the second gives the most important optional-filter behavior with a concrete example. It is appropriately sized and front-loaded.

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

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

The description gives a usable mental model for a search tool, and annotations plus the detailed input schema cover safety and parameters. However, there is no output schema, and the description leaves the result shape and the relationship to brain_expand implicit, so it is not fully complete on its own.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description's concrete wing/hall example is a small addition, but it does not meaningfully explain parameters beyond what the schema already provides.

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 and resource ('Search your knowledge brain') and states the output ('pages ranked by relevance'). It is clear, but it does not explicitly distinguish itself from sibling search-like tools such as discover or brain_expand.

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 tool's purpose implies when it should be used, and the example of wing/hall filtering gives context for narrowing a search. However, there is no explicit guidance about when to choose this over sibling tools or situations where it should not be used.

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

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

The description adds meaningful behavioral context beyond the annotations by explaining that drawers_enabled stores raw tool output alongside summaries for richer recall. It aligns with readOnlyHint=false and destructiveHint=false, and while it doesn't mention side effects or persistence, the annotation coverage lowers the burden.

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

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

A single front-loaded sentence with one useful parenthetical; no filler or repetition of schema details. Every part contributes to understanding the tool.

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 two-action tool with full schema coverage and annotations, the description is largely complete: it defines the settings scope and explains the supported setting. Minor gaps are the lack of return-value hints for 'get' and no explicit usage guidance, but these are not critical for a tool this small.

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 semantic value for the setting parameter by explaining the purpose of drawers_enabled. It does not add detail for action or value, but the schema already documents those sufficiently.

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

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

The description states a clear verb and resource: 'View and toggle your brain settings,' and names the one supported setting with its effect. It does not explicitly contrast with sibling tools such as brain_status or brain_update, so it stops short of a full 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?

The description gives no guidance about when to prefer this tool over the many brain_* siblings, and it does not state exclusions or conditions for using get versus set. The schema covers mechanics, but the description leaves alternative-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 establish read-only, idempotent, non-destructive behavior, so the description only needs to add context. It adds the scope ('personal and team brain') but does not disclose return shape, pagination, or any other behavioral details.

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

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

A single sentence front-loads the action and object, then narrows scope. No filler or redundancy.

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 status tool, the description covers the essential information an agent needs. It could be more explicit about what a 'recent pages' response contains, but the annotations and simple profile keep the gap minor.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the description bears no parameter-documentation burden. It clearly conveys what the operation reports.

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 ('View') and identifies clear resources: 'brain page counts and recent pages' for personal and team brain. It is distinct enough from siblings like brain_query, though it does not explicitly name an alternative.

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 purpose implies when to use it — when the user needs brain page counts or recent pages as status information. It does not explicitly state when not to use it or compare it with related brain tools like brain_query or brain_settings.

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 that this is a non-read-only, non-destructive, idempotent operation. The description adds useful permission context ('Moving a page to team scope requires team admin role') and explains the re-filing concept, but it does not go further into side effects like version creation behavior beyond what the parameter schema already states.

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 deliver the core purpose, the main capabilities, and a key access constraint without filler. The primary action is front-loaded, and each sentence serves a distinct informative purpose.

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 10-parameter tool with no output schema, the description plus the rich parameter schema adequately covers purpose, re-filing semantics, scope movement, and admin requirements. It falls just short of a 5 because there is no indication of what the tool returns after an update, which would help the agent know what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying wing/room/hall together as a re-filing mechanism and explaining scope movement in terms of a real-world use case. It does not merely repeat parameter descriptions, though some points like the team admin requirement are already present in the schema.

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

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

The description opens with a specific verb and object: 'Edit an existing brain page's content or metadata.' It also explains the key operations (re-filing via wing/room/hall, moving scope) which clearly differentiates it from siblings like brain_add or brain_delete. No ambiguity remains about what this tool does.

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 a clear context for updating pages and even provides a concrete scenario for scope changes ('when an auto-ingested page landed in the wrong place'). However, it never explicitly contrasts with alternatives such as brain_add for creation or brain_delete for removal, leaving some usage 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying what each wing returns: rooms, halls, page count, and last-updated time. No contradictions 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?

Two sentences carry all the essential information: what the tool lists, what it returns, and how to use the result. The definition is front-loaded with the core concept and the usage guidance is placed at the end without redundancy.

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

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

For a read-only list tool with one optional parameter and no output schema, the description provides enough context: the resource type, examples, return contents, and the follow-up action. An agent can successfully select and invoke this tool without further clarification.

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 only parameter (include_team) is already documented in the schema. The description does not add further meaning about parameters, which is acceptable because the schema handles the full burden. 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 names a specific verb and resource ('List the wings of your brain') and clarifies that wings are the top-level knowledge areas with examples like 'engineering' and 'family'. It also distinguishes itself from sibling tools by describing the hierarchical structure (wings containing rooms and halls) and pointing to brain_query as the downstream consumer.

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 an explicit usage context: 'Use this to discover the right wing/hall to pass to brain_query.' This tells an agent when to call the tool and why. It does not mention alternatives or when not to use it, but the tool's discovery role is clear enough given the sibling list.

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 indicate this is a mutating, non-idempotent action, and the description's 'Connect a new...' phrasing confirms it creates persistent state. However, it does not disclose side effects such as whether an OAuth consent flow is triggered, whether duplicate connections are rejected or replaced, or how auth tokens are stored. The description adds some value beyond the annotations but leaves behavioral details underexplained.

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 short sentences with no filler. The main action is front-loaded, and the mode-specific guidance is compact and easy to scan. Every sentence earns its place.

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

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

For a 10-parameter tool with no output schema and no required parameters, the description provides useful mode routing but does not state the required parameter combinations as strict constraints, nor does it describe the return value or expected outcome after a successful add. An agent would benefit from knowing what happens after calling this tool, such as whether a connector ID is returned or how to verify success via connector_list.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping parameters into three usage modes and naming the key combos: type+kind, catalog_slug, and url+auth_type. It does not discuss every parameter like billing or header_name, but those are already well-documented 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 names a specific action and resource: 'Connect a new OAuth account or MCP server.' It then enumerates the three supported modes (OAuth, MCP catalog, custom MCP), making the tool's scope immediately clear and distinguishing it from sibling tools like connector_list and connector_remove.

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 explicit condition-to-parameter guidance: 'For OAuth: pass type: "oauth", kind: "slack". For MCP catalog: pass catalog_slug. For custom MCP: pass url + auth_type.' This tells the agent exactly how to invoke the tool in each scenario. It does not name alternative sibling tools for exclusion, but the usage context for adding a connector is clear.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior; the description adds meaningful behavioral detail: default summary, slug switches to per-connector detail exposing every tool, type filters, and include_available extends the result set. It doesn't describe pagination or the exact list envelope, but the added context goes 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?

Four short sentences, front-loaded with the core action, each sentence maps to one distinct behavior (base list, slug detail, type filter, include_available). No filler or unnecessary repetition beyond what is useful for correct invocation.

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 covers the main output modes (summary vs. per-connector detail including exposed tools) and all optional switches. The 'context' parameter is left to the schema, but schema coverage is complete and there are no required parameters; overall an agent has enough to call this 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 already documents all 4 parameters at 100% coverage, so the baseline applies. The description mostly restates schema semantics ('Pass slug for detail') and adds only modest color ('including every tool the connector exposes', 'catalog MCPs you can connect'). No significant new parameter meaning is introduced.

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 precise action ('List connected accounts and MCP servers') and clarifies the summary-vs-detail split via slug. The resource is distinct from connector_add/connector_remove/connector_permissions and from credential_list, so an agent can select it correctly.

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 explicit invocation guidance: pass slug for detail, use type filter, set include_available to include unconnected catalog MCPs. It doesn't name alternative tools or state when not to use this tool, so it stops just short of the strongest level.

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 only state the tool is not read-only, not open-world, not idempotent, and not destructive. The description adds useful behavioral context: 'set' updates one tool's rules, 'list' shows current rules, and team scope requires admin role. It does not detail all side effects of mutation (e.g., immediate enforcement or overwrite semantics), but it goes beyond what annotations convey.

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 with strong front-loading: the opening sentence summarizes the tool's purpose and scope, the second explains the two invocation modes, and the third flags the admin precondition. No filler, every sentence earns its place.

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

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

Given the tool's complexity (15 parameters) and absence of an output schema, the description covers the essential workflow: how to list, how to set, where to get the slug, and an important access constraint. It doesn't describe the shape of the 'list' response, but that is an acceptable gap when parameters are fully documented in 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 description coverage is 100%, with detailed descriptions for all 15 parameters, so the description correctly does not restate each parameter. It adds marginal workflow context (pass slug, choose action) that is partially redundant with the schema's own action description. This is an adequate but not exceptional supplementation.

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-resource pair: view or set permissions for tools on a connected MCP server. It enumerates the permission dimensions (allowed tools, rate limits, budget caps, argument restrictions) and positions the tool relative to connector_list by mentioning the connector slug, making its purpose distinct from connector lifecycle siblings.

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

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

The description gives explicit when-to-use guidance for the two actions (list vs set) and points to connector_list as the source for the slug. It notes the admin role requirement for team scope. It does not explicitly name alternative tools to use instead, but the action breakdown and prerequisite reference provide clear operational 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 indicate destructive, non-readonly, idempotent behavior, but the description adds no additional behavioral context such as what gets disconnected, whether credentials are revoked, or reversibility. It simply restates the action without enriching the agent's understanding of consequences.

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

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

The description is extremely concise, with no filler or repetition. 'Disconnect a connector. Pass slug.' front-loads the operation and the key required argument, making it easy to parse quickly.

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 destructive tool with no output schema, the description is too thin. It does not explain the effects of disconnecting, how the type or billing scopes influence the operation, or how the result is reported. The schema covers parameters, but the behavioral context needed for confident 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 description coverage is 100%, so the baseline is 3. The description only repeats 'Pass slug' and adds no meaning beyond the schema's existing parameter documentation for slug, type, or billing.

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 the specific verb 'Disconnect' with the resource 'connector', which clearly distinguishes this tool from siblings like connector_add, connector_list, and connector_permissions. The instruction to pass the slug further narrows the action without ambiguity.

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 offers no guidance on when to use this tool versus alternatives, and it does not mention prerequisites such as requiring an existing connector or how to discover the slug. Usage is only implied by the operation name, not explicitly stated.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation, and the description does not contradict them. However, the description adds no behavioral detail beyond the action itself, such as whether the previous default is replaced or whether the referenced credential must already exist. This is acceptable but thin given the annotations cover the safety profile.

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, direct sentence with no redundant wording. It front-loads the verb and object, making the core operation immediately clear.

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

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

For a low-complexity tool with fully documented parameters and annotations covering safety and idempotency, the description is mostly complete. Minor gaps remain around behavioral consequences, such as overwriting the current default, and whether the credential entry must already exist.

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 has 100% description coverage for name, label, and context, so the schema already documents each parameter. The description does not add any parameter-level meaning beyond what the schema provides, which aligns with the baseline of 3.

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 ('Set') and resource ('default value for a multi-value credential'), which clearly identifies the tool's purpose. It is distinguishable from sibling tools like credential_save and credential_delete by the concept of a default entry, though it does not explicitly name those alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives such as credential_save, credential_list, or credential_delete. It does not state prerequisites, such as the credential needing multiple saved entries, nor does it explain when setting a default is appropriate.

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 include destructiveHint=true, and the description adds the key destructive nuance that omitting label removes ALL entries for the credential name. This goes beyond the schema and meaningfully warns about the destructive scope. 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?

Two sentences with no filler. The core action is front-loaded, and the conditional destructive behavior is stated immediately after. Every sentence earns its place.

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

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

For a destructive deletion tool with a full parameter schema and no output schema, the description covers the essential behavioral decision: label vs no label. It does not address edge cases like nonexistent credentials or confirmation behavior, but the annotations and schema cover most remaining context 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?

Schema description coverage is 100%, so the schema already explains all parameters. The description reinforces the label semantics (specific entry vs all entries) but adds little new meaning beyond the parameter descriptions already present.

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 ('Remove') and resource ('saved credential'), and clearly explains the two deletion modes: specific label vs all entries. This distinguishes it from sibling credential_* tools and leaves no ambiguity about what the tool does.

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 condition for using the label parameter is described, giving some usage guidance. However, there is no explicit comparison to alternatives like credential_save or credential_list, so tool-selection guidance is only implied by the delete verb and title.

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=true and idempotent=true, so the safety profile is covered. The description adds the scoping constraint 'for a specific credential' but this is also visible in the schema's required 'name' parameter. No additional behavioral traits (e.g., return format, prerequisites) are disclosed, but the annotations lower the bar.

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

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

The description is a single, front-loaded sentence with no filler. Every word ('Get', 'setup instructions', 'specific credential') earns its place, making it appropriately sized for the tool's simplicity.

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

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

For a one-parameter, read-only guide tool with full schema coverage and safety annotations, the description is mostly complete. It could hint at how to discover valid credential names (e.g., via credential_list), but the schema examples partially cover this. The absence of an output schema is mitigated by the self-explanatory 'setup instructions' return intent.

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 parameter 'name' is fully documented with examples. The description's phrase 'for a specific credential' adds no new meaning beyond the schema's 'Credential name' definition. Baseline 3 is appropriate because 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?

The description states a specific verb ('Get') and resource ('setup instructions for a specific credential'), which clearly distinguishes it from sibling credential tools like credential_list, credential_save, and credential_delete. The phrase 'setup instructions' uniquely identifies the tool's function among the sibling set.

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 when to use the tool: whenever an agent needs setup instructions for a credential. It provides a clear context, though it does not explicitly name alternatives or exclusion conditions. This meets the 'clear context, no exclusions' level.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful mode information (summary vs detail, catalog inclusion) but does not disclose additional behavioral traits such as return format, pagination, or permission requirements. This is adequate given the strong 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 short sentences with no filler. It front-loads the core action ('List saved credentials') then immediately provides the variations. Every sentence earns its place and there is no redundant restatement of the title.

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

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

For a simple read-only listing tool with three optional parameters, all covered by the schema and annotations, the description is nearly complete. It explains both listing modes and the catalog flag. Minor gaps remain around the exact return shape (summary vs detail) and the meaning of 'full credential catalog', but these are not critical for invoking the tool correctly.

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

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

Schema description coverage is 100%, so every parameter (name, context, show_available) is already documented clearly in the input schema. The description reinforces the name and show_available behaviors but adds little beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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 action and resource: 'List saved credentials (summary) or detail on one.' It clearly distinguishes credential_list from sibling tools like credential_save, credential_delete, and credential_default by focusing on the listing behavior. The summary/detail distinction adds precision beyond the title.

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 parameter-level guidance ('Pass name for detail view', 'Pass show_available: true') but does not explicitly discuss when to use this tool versus alternatives. The context is implied by the word 'list', but there is no explicit exclusion of credential_save/delete/default or mention of 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?

With annotations already indicating a non-read-only, idempotent, non-destructive operation, the description adds meaningful context: saved keys persist across sessions and are used automatically. It does not contradict the annotations and gives useful side-effect awareness beyond the schema.

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 two short sentences with no filler. The core action is stated first, followed immediately by the most important behavioral consequence, making it easy for an agent to parse quickly.

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 moderately simple tool with full schema coverage and helpful annotations, the description covers the essential purpose and persistence behavior. It could be slightly more complete by mentioning that saving an existing name may overwrite it, but the idempotent annotation and schema descriptions reduce the need.

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 input schema already fully documents all five parameters. The description does not need to add parameter detail, and the schema handles meaning for name, label, value, context, and is_default appropriately.

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

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

The description uses a specific verb-resource pair, 'Save a credential', and further scopes it to a 'BYOK provider API key' with a clear persistence guarantee. This separates it from the delete/list/default/guide credential siblings even without naming 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?

The description implies when to use the tool: when a credential should persist across sessions and be used automatically. However, it does not explicitly contrast with alternatives like credential_delete, credential_default, or credential_list, 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying that negative-balance warnings and rate limits are included, going beyond a simple 'get balance' statement. No contradictions 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 a single, compact sentence that front-loads the key returned values and ends with the scoping phrase 'for the active context'. Every word contributes meaning.

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

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

Given a zero-parameter, read-only tool with no output schema, the description adequately enumerates the returned information: balance, plan tier, rate limits, and warnings. It could clarify what 'active context' refers to, but that is a minor gap for such a simple 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 tool has zero parameters and the schema is empty, so the description carries no parameter burden. Baseline 4 is appropriate because there is nothing to explain about parameters.

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

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

The description states the exact data returned: current balance, plan tier, rate limits, and negative-balance warnings for the active context. This clearly identifies the resource (credits balance) and distinguishes it from sibling tools like credits_usage or top_up_credits.

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

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

The description implies this tool should be used when an agent needs current credit balance, plan tier, or rate limit status. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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?

No contradiction with the annotations. The annotations already cover read-only, idempotent, non-destructive behavior, and the description adds useful behavioral context: results are sorted by cost, leftover items are rolled into _others, and output granularity changes with detail. This is meaningful context beyond the schema.

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 short sentences deliver the purpose, key parameters, and output ordering/rollup behavior without fluff or repetition. Every clause earns its place, and the opening sentence gives the domain immediately.

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

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

For a read-only reporting tool with a fully described schema, the description covers purpose, grouping, sorting, and rollup well enough. The main gap is that 'summary or history' is not fully disambiguated, especially since the schema's offset mentions 'history mode' without a clear mode parameter.

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 each parameter already has a meaningful description, so the baseline is 3. The description repeats scope and detail hints but adds no new parameter semantics, which is acceptable given how thorough the schema already 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?

The description identifies the resource as credit usage and states it returns a summary or history grouped by scope and detail, sorted by cost with an _others rollup. This goes beyond the name and title, though it lacks an explicit retrieval verb and does not call out the sibling credits_balance.

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

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

There is no explanation of when to choose this tool over credits_balance or top_up_credits, and no when-not-to-use guidance. 'Usage summary or history' states the domain but not a decision rule; the rest of the description mostly restates parameter 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: exact tool-name queries return full schemas and examples, and every response includes a top-level connectors array listing connected SaaS accounts. This helps the agent know what to expect from the response.

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 its core purpose and then provides compact, useful sections: examples, the call flow, connectors behavior, and categories. It is slightly longer than necessary because the category list duplicates the schema enum, but every other sentence earns its place.

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

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

Given there is no output schema, the description covers the important return behavior: tool+skill results, exact-name schema retrieval, and the connectors array. It does not detail the exact structure of the standard tool-results list, but it provides enough for an agent to use discover effectively.

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

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

Schema coverage is 100%, so the schema already documents query and category. The description adds semantic value by showing how to use the query parameter: plain-language requests, categories, '*', or exact tool names like 'seo'. It also lists the category values in prose, reinforcing the enum meaning.

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 ('Find') with a clear resource ('the right ToolRouter tool for your task'), and includes concrete examples like 'analyze a website' and 'check DNS records'. It also distinguishes itself from the use_tool sibling by laying out the discovery flow, so an agent can tell it apart from invocation tools.

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

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

The description explicitly explains when to use discover: when you need to find the right tool, whether via plain-language task description, category, or exact tool name. It also names the downstream alternative, use_tool, in the flow 'discover → pick a tool + skill from results → call use_tool', and gives context on using the connectors array to pick the right account.

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 only signal the generic hints (readOnly=false, destructive=false, etc.), so the description carries most of the burden. It goes far beyond the annotations by disclosing report storage and review cadence ('Reports are stored and reviewed within hours'), the 5-per-hour rate limit, and explicit data-safety constraints (do not include chat history, personal data, API keys, secrets). It also clarifies that the tool is for bugs only, not expected errors. The only minor gap is not describing whether the report triggers a confirmation or response, but that's a small omission given the otherwise strong disclosure.

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

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

The description is tightly packed and front-loaded: it starts with the core purpose, immediately gives the decision rule, lists required content, lists forbidden content, states the SLA, lists exclusions, and ends with the rate limit. Every sentence earns its place. While it is longer than typical descriptions, it needs the length because it is a safety-sensitive reporting tool with explicit do/don't guidance; nothing is redundant.

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

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

Given the tool's complexity — 10 parameters, two required, a safety-sensitive reporting scope, and no output schema — the description covers the essential decision boundaries, content rules, and limits. It tells the agent exactly what to include and what to exclude, which is the core risk area for this tool. A small completeness gap is that the description doesn't explicitly mention the 10 parameters by name, but the schema covers that entirely, so the description's role is to clarify when and how to use those parameters, which it does.

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

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

Schema description coverage is 100%, so the baseline is 3 — the schema already documents every parameter in detail. The description adds some context about what 'relevant ToolRouter errors' means and what to omit, but it doesn't add significant semantic meaning beyond the schema. The connection between the description and the parameters is implicit: the description mentions call IDs, input shape, retries, expected behavior, and those parameters all exist in the schema, but the description doesn't elaborate on their format or usage beyond the schema already does.

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 and resource — 'Report a ToolRouter platform bug' — and explains the exact condition: when the issue is on our side and a tool crashed, returned malformed data, timed out, or behaved inconsistently. This clearly distinguishes it from regular task execution and from other feedback tools like feedback_request_tool or feedback_review. The statement 'Skip this for expected errors...' further disambiguates it from tools that handle normal errors.

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 tells when to use this tool ('Use this when you suspect the issue is on our side') and when NOT to use it ('Skip this for expected errors like invalid input, missing credentials, insufficient balance, rate limits, or genuine "not found" results — those aren't bugs'). It also names the context — blockage from completing the user's task — leaving no ambiguity about its intended trigger conditions.

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 are all false and do not reveal much, but the description adds meaningful behavioral context: requests are not fulfilled immediately but 'go straight to the team,' there is a 5-per-hour limit, and sensitive data must not be included. This goes beyond the structured annotations and helps the agent set expectations about the tool's real-world effect.

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 only five short sentences, and each one earns its place: purpose, usage condition, content guidance, routing behavior, and rate limit. The most important information is front-loaded, and there is no filler or repetition of schema details.

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

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

For a tool with four simple string parameters, no output schema, and no nested objects, the description covers all operational essentials: when to invoke it, how to fill it out, what not to include, what happens after submission, and how often it can be used. An agent can invoke this tool correctly without additional 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?

Schema description coverage is 100%, so each of the four parameters is already clearly documented in the input schema. The tool description adds general guidance about writing capabilities in plain terms and omitting secrets, which applies to the parameters as a whole, but it does not add parameter-specific meaning beyond what the schema already provides.

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: 'Ask ToolRouter to build a tool that does not exist yet.' This clearly distinguishes it from discover, use_tool, and the other sibling tools that operate on existing tools or data. It also adds a triggering condition (discover returned nothing useful) that anchors the tool's role.

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 tells the agent when to use this tool: 'Use this when discover returned nothing useful for what the user needs.' This names the alternative or prior step, gives a clear condition, and additionally supplies content constraints and a rate limit, leaving little ambiguity about when it is appropriate.

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

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

Annotations already indicate readOnlyHint=false, so the description's 'Submit' adds no new behavioral insight. The description does not disclose what happens after submission, e.g., whether the review is stored, can be updated, or is anonymous, even though idempotentHint=true suggests repeated submissions are safe.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. It is concise, though it is so short that it sacrifices informative depth that could have been included without harming readability.

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 submit operation, the schema and annotations cover the basic requirements: required params, rating bounds, and safety hints. However, the description doesn't mention optionality of the review text, expected effects, or whether submission overwrites prior feedback, so it remains minimally adequate rather than 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?

Schema description coverage is 100%, so the parameters are already well-documented in the input schema. The description adds minimal semantic value by mentioning 'review' and 'star rating', but it doesn't enrich understanding of the 'tool' parameter or any parameter interactions beyond what the schema provides.

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 action ('Submit') and resource ('a review or star rating'), which is more specific than the title alone. It is not as strong as it could be because it doesn't explicitly differentiate from sibling tools like feedback_request_tool or feedback_debug, but the core purpose is 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 offers no guidance on when to use this tool versus alternatives such as feedback_request_tool or feedback_debug. There are no exclusions, prerequisites, or conditions given, leaving the agent to infer the appropriate context from the tool's name alone.

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

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

Annotations already declare destructiveHint=true, and the description extends this with 'Cannot be undone,' confirming irreversibility. It also adds auth context — owner/admin role for team files — which is genuinely new information beyond what annotations provide. 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?

Three short, front-loaded sentences: the core action leads, followed by the irreversibility warning and the permission condition. Every sentence earns its place and there is zero filler.

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

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

For a simple one-parameter destructive tool with no output schema and no nested objects, the description covers the operation, its permanence, and the auth gate. Minor gaps remain around return values and error behavior for nonexistent files, but the low complexity and supportive annotations make this largely sufficient.

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 file_id fully described as 'The file ID to delete,' so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already states.

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 ('Delete') and resource ('a file'), making the operation unambiguous. The delete verb inherently separates it from sibling file tools (file_list, file_read, file_write), though it never explicitly names or contrasts 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?

Usage is implied rather than explicit: an agent infers this is for removing files because no sibling tool performs deletion of a file. The description adds a useful prerequisite ('For team files: requires owner/admin role'), but there is no when-not-to-use guidance or explicit alternative 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral nuance by stating that an optional query changes the operation to semantic search. No contradictions with annotations exist.

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 with no filler. It front-loads the core action, then immediately conveys semantic search behavior and the supported filters, making it efficient and easy to scan.

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 100% schema coverage and read-only annotations, the description plus structured data fully support correct invocation. It conveys the two usage modes, available filters, and the non-destructive nature of the operation, which is sufficient for a list/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 100%, so the baseline is 3. The description adds value by clarifying that 'query' triggers semantic search and by naming the primary filters supported. It does not enumerate every parameter, but the schema covers the remaining ones well.

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 'List or search files', a specific verb and resource, and clarifies that an optional query triggers semantic search. This clearly distinguishes the tool from sibling tools like file_read, file_write, and file_delete, even without naming 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?

The description gives clear context: use it to browse files or run a semantic search by providing a query, with the listed filters available. It does not explicitly state when to prefer alternatives like file_read, but the list/search intent is clear enough for 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuinely useful behavioral context beyond those flags: text files return content inline while binary files (images, video) return a download URL. This directly shapes an agent's expectation of the response without an output schema present.

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

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

Two short sentences with zero wasted words. The core action is front-loaded first, and the behavioral caveat (text vs binary return behavior) is placed second where it belongs. Every sentence earns its place.

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

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

For a one-parameter read-only tool whose safety profile is fully covered by annotations, this is complete. The description specifies return behavior for both file categories, compensating for the absence of an output schema. Error cases and permission requirements are minor gaps at this level of complexity.

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 file_id fully documented including a concrete example ('ast_a1b2c3d4e5f67890'). The description adds no parameter-specific detail, but the baseline 3 applies because the schema already carries the full documentation burden for the single 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?

States a specific verb and resource ('Read a file's full content') and immediately clarifies the behavioral scope with the text/binary distinction. The name plus description clearly differentiate it from file_list, file_write, and file_delete without needing to open any 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?

Usage context is implied — an agent can infer this is for retrieving a file's full content — but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as file_list for discovering file IDs or file_write for modifying content. The description does not actively mislead, but leaves selection logic 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?

The description discloses a multi-step binary upload flow beyond the sparse annotations, but it instructs agents to call with 'binary: true' even though no such parameter exists in the schema. This is misleading and leaves the actual upload behavior unclear; annotations are all false and do not clarify side effects, overwrite, or auth requirements.

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 with no filler; the core purpose is front-loaded and the upload workflow is stated in minimal steps. Every sentence earns its place.

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

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

Even though the schema is detailed, the definition omits the connection between the described binary workflow and the actual schema parameters, does not describe return values (no output schema), and leaves conditional requirements (file_id, section, name) to be inferred. The missing 'binary' parameter is a critical completeness 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?

Schema coverage is 100%, so the baseline would be 3, but the description's only parameter-level addition references a nonexistent 'binary' parameter. Rather than adding useful semantics, it conflicts with the input schema and may cause an agent to attempt an invalid call.

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 action and resource ('Create or update a file') and covers the three mode variants, making the write intent clear against file_read/file_list/file_delete siblings. It lacks explicit sibling differentiation, but the scope is 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?

It states when to use the tool (create/update files) and gives a conditional binary upload workflow. It does not explicitly list exclusions or alternatives, but the write-vs-read/delete context is clear 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds the useful 'active billing context' scoping detail, but does not mention return format, ordering, pagination, or other behavioral nuances. With annotations carrying the safety burden, this is adequate but not rich.

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 with no filler. It front-loads the action, resource, and scope, making it easy for an agent to parse and act on quickly.

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

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

For a simple, read-only list tool with one optional parameter and robust annotations, the description is largely complete. It could mention what fields are returned or clarify how the active billing context is determined, but an agent can likely invoke this tool correctly based on the name, scope, schema, and annotations.

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 fully documents the only parameter, limit, including default, minimum, and maximum. The description adds no parameter-level meaning, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description states a clear verb ('List'), a specific resource ('invoices'), and a scope ('active billing context'), which is enough to distinguish it from the many sibling list tools like account_list, connector_list, or file_list. It is not a tautology and immediately tells an agent what the tool does.

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 phrase 'for the active billing context' gives a clear context for when the tool applies. However, it does not explicitly discuss when not to use it or name alternatives for other billing-related operations such as credits_usage or subscription_manage, so it falls slightly short of fully explicit usage 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 the operation as destructive and idempotent, so the description does not need to repeat that. It adds the useful precondition that the job must be running, but does not describe what happens after cancellation or any side effects beyond what annotations convey.

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, four-word sentence with no filler or redundant information. It front-loads the action and the target resource effectively.

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 cancellation tool with annotations covering destructive behavior, the description is mostly sufficient. It could clarify post-cancellation behavior or error handling for non-running jobs, but these are minor gaps given the full schema coverage and annotation 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?

The input schema fully documents the single job_id parameter with 100% coverage, so the description does not need to add parameter details. The description provides no additional semantic meaning about job_id, but the schema already carries that burden.

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 the specific verb 'cancel' and clearly identifies the resource as 'a running job,' so the operation is unambiguous. It does not explicitly name sibling tools like job_get or job_list, but the action is distinct from 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?

The phrase 'running job' implies the tool is intended for jobs currently in progress, providing a usage context. However, it does not explicitly state when not to use it or mention alternatives such as job_get for checking job status.

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

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

The description adds behavioral context beyond the annotations: it specifies the possible status values, that a result is only returned at a terminal state, and that polling is expected. Annotations already cover read-only/idempotent/non-destructive behavior, so this additional return-semantics detail earns solid credit.

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. The core purpose is front-loaded, the terminal statuses are enumerated, and the polling directive is actionable. Every sentence earns its place.

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

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

For a simple single-parameter polling tool with no output schema, the description covers what the agent needs: when to call it, what statuses to expect, when a result appears, and that repeated calls may be necessary. 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?

Schema description coverage is 100%, so the schema already fully documents job_id. The description does not need to add parameter meaning. Baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get job status and result.' It further clarifies the exact return semantics (running/completed/failed, with result when terminal), making it clearly distinguishable from sibling tools like job_list and job_cancel.

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 operational guidance: 'Keep polling until you get a terminal status.' This tells the agent how to use the tool correctly. It does not explicitly contrast with job_list or job_cancel, but the polling instruction is strong and contextually sufficient.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that only active/recent jobs are listed, but does not describe default pagination or response shape.

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 short sentence with the action and scope front-loaded, followed by the optional filter. No wasted words; appropriate for such a simple tool.

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 combination of schema, annotations, and description is sufficient to invoke the tool correctly, but the phrase 'active and recent' is somewhat vague and there is no return-format hint since no output schema exists. For a simple read-only list this is acceptable but not fully fleshed 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 both limit and status have descriptions; the description adds no meaning for limit but confirms status filter is optional. Baseline 3 applies since the schema carries the 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 ('List') and resource ('your active and recent jobs'), and the optional status filter clarifies scope. It is clearly differentiated from job_get (single job) and job_cancel (mutation), though it doesn't name them 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?

It states the core use case (listing active/recent jobs) and notes an optional status filter, implying how to narrow results. However, it never mentions alternatives such as job_get for retrieving one job's details, so routing guidance is only implied.

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 discloses the critical behavioral trait that the secret is returned only once and should be saved immediately. This goes beyond the annotations, which only indicate non-idempotent and non-read-only behavior without specifics.

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

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

Two short sentences with no filler. The core action and the critical caveat are both stated upfront, making the description easy to parse and act on.

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 fully documented parameter, no output schema, and the key behavioral warning about one-time secret retrieval, the description is complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% for the single 'name' parameter, and the schema already explains its purpose and provides an example. The description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Create a new API key.' It also immediately distinguishes this from sibling operations like key_list and key_delete by focusing on creation and the one-time secret return.

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 it clear the tool is for creating new keys but does not explicitly mention alternatives or conditions for when to use key_list or key_delete instead. The usage context is implied rather than stated.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds a meaningful behavioral guard: 'Refuses to revoke the currently-authenticating key', which is important edge-case information not captured by annotations. No contradiction exists between the description and 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?

Two sentences with no filler. The action is front-loaded and the caveat follows immediately, making it scannable for an agent.

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

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

For a one-parameter destructive tool with rich annotations, the description covers the core behavior and the key refusal edge case. It does not state the success/error return format, but absent an output schema this is a minor gap for such a simple operation.

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 covers key_id with 100% description coverage, including the source '(from key_list)'. The tool description itself adds no additional parameter semantics, but the schema already provides what the agent needs, so baseline 3 is appropriate.

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

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

States the operation precisely: 'Revoke an API key.' This is a specific verb and resource that clearly distinguishes it from siblings like key_create and key_list. The additional refusal note is a unique behavioral detail that further identifies the tool's scope.

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

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

The description implies this tool is for revocation, but it doesn't explicitly instruct when to use it instead of sibling key tools. There is no mention of alternatives like key_create (to rotate) or key_list (to enumerate). The refusal condition provides limited context but doesn't explain what to do if the current key must be rotated.

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 read-only, idempotent, non-destructive behavior. The description adds the behavioral nuance that the summary view is default and detail requires key_id, which is useful beyond the annotations. No contradiction detected.

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

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

Two short sentences, front-loaded with the primary action, and every word earns its place. 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 simple read-only tool with one optional parameter and strong annotations, the description covers both invocation modes and expected behavior. It could specify return fields since there is no output schema, but this is not a material gap for correct invocation.

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

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

The schema already documents key_id with 100% coverage: 'Key ID for detail view. Omit to list all.' The description repeats this guidance without adding new semantic meaning, so the baseline score of 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 the verb, resource, and dual mode explicitly: 'List API keys (summary) or get detail on one key.' This clearly distinguishes it from sibling tools like key_create and key_delete, and the title aligns with the description.

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 clear functional guidance: omit key_id to list all, pass key_id to get detail. It does not explicitly mention when to avoid the tool or prefer an alternative, but the usage context is clear 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?

The description adds no behavioral detail beyond what the annotations already provide; it simply restates the action. Annotations indicate a safe, read-only, idempotent operation, but the description does not disclose output format, filtering behavior, or team context semantics.

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

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

The description is a single front-loaded sentence with no unnecessary words, which is efficient and easy to parse. Combining it with the schema keeps the definition tight, though it could have briefly mentioned the team context to improve clarity.

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

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

For a simple tool with one optional parameter and no output schema, the description is mostly adequate, but it leaves some details implicit. It doesn't state that the context parameter can switch between personal and team views, nor what the resulting outfit list contains; however, the schema covers the parameter aspect.

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 fully documents the only parameter 'context' with the description '"personal" (default) or "team:<id>"', so the tool description doesn't need to add parameter meaning. Schema coverage is 100%, meriting the baseline score of 3.

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 'List your outfits' uses a specific verb and resource, clearly identifying the tool's function. It is easily distinguishable from sibling tools by the unique 'outfits' resource, though it doesn't add additional scope details such as context filtering.

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

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

The description implies usage when a user wants to list their outfits, but provides no explicit when-to-use guidance or comparison with alternatives. It doesn't mention when to use the team context parameter or any prerequisites.

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 cover the safety profile (readOnlyHint, idempotentHint, non-destructive), and the description does not contradict them. The only extra behavioral signal is 'your', implying user-scoped results; it does not mention pagination, ordering, or error behavior, so the description adds minimal value beyond 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 words and contains no redundancy or filler. It is front-loaded with the verb and object, which is ideal for a minimal tool.

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

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

For a one-parameter, read-only list tool, the description is minimally adequate, but it leaves the return shape and the effect of the optional 'context' parameter to be inferred. With no output schema, a phrase like 'returns the user's saved personas, optionally scoped by context' would make it 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?

Schema description coverage is 100%, so the single 'context' parameter is already fully documented in the schema. The description adds no parameter semantics of its own, so the baseline 3 applies.

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

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

The description clearly identifies the action (list) and target (personas), and the possessive 'your' communicates user scope. It does not add detail that distinguishes it from sibling list tools beyond the resource name itself, so it is clear but not exceptionally differentiated.

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

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

No guidance is given for when to use this tool versus sibling list tools such as account_list, connector_list, or scene_list. There are no prerequisites, exclusions, or alternative routing signals, leaving the agent to infer usage from the tool name.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the scoping detail that the products are 'yours', but it does not mention pagination, limits, or return shape. There is 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 a single, front-loaded sentence with no wasted words. It conveys the essential purpose immediately and is appropriately short for a simple list operation.

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 simple one-parameter schema and robust annotations, the description is nearly sufficient. It lacks an explicit note about the context parameter or return type, but the schema covers the parameter and 'List' implies an array result.

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 100% for the single optional context parameter, including the 'personal' default and 'team:<id>' format. The description adds no further parameter meaning, so it remains at baseline for high schema coverage.

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

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

The description clearly states the action ('List') and the resource ('your products'), making the core purpose easy to identify. It does not explicitly distinguish itself from sibling list tools, but the resource name is unique enough that an agent can infer 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?

There is no explicit guidance on when to use this tool versus alternatives. The phrase 'List your products' implies usage when the agent needs to retrieve products, but no alternatives or exclusions are mentioned.

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 the tool as read-only, idempotent, and non-destructive, so the description carries a lighter burden. It adds a mild scoping cue ('your') but does not disclose return format, pagination, authentication needs, or the team: context option. There is no contradiction with the annotations.

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

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

The description is a single, front-loaded sentence with no filler. It is efficient, though it could have incorporated the context parameter or a brief usage hint without becoming 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?

For a simple list tool with strong read-only annotations and one optional parameter, the description is mostly adequate. However, 'your scenes' could misleadingly imply personal-only scope, while the schema permits 'team:<id>', and no output/return behavior is described due to the lack of an output 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 description coverage is 100%, and the schema already explains the only parameter, context. The description adds nothing about this parameter, but for a single fully documented parameter, 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 states the action ('List') and the resource ('your scenes'), and the possessive 'your' signals user scope. It distinguishes the tool by its resource type, and no scene-specific sibling alternatives appear to create ambiguity.

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

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

The intended use is implied by 'List your scenes' — an agent can infer this is the tool for retrieving scenes. However, there is no explicit guidance about when to use it versus alternatives, no exclusions, and no mention of the context parameter's role in selecting personal vs. team scenes.

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

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

Annotations already indicate non-read-only and non-idempotent behavior, and the description adds that the tool returns a URL for the user to open. However, it does not disclose that 'subscribe' may initiate a checkout flow or that opening the URL can lead to subscription changes. This understates the behavioral impact, especially since readOnlyHint is 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?

The description is short and front-loaded with the main outcome. There is minor redundancy between 'portal' and 'billing portal', but overall the text is scannable and every sentence contributes meaning.

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

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

There is no output schema, so describing the return value as a URL is helpful. However, the description fails to cover the 'subscribe' action and the corresponding checkout URL, making it incomplete for a tool whose action enum includes both subscribe and manage. An agent handling a 'start a subscription' request would be underinformed.

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 clear descriptions and enums for both 'action' and 'tier'. The description adds little beyond the schema, except indirectly implying 'upgrade' behavior. Baseline 3 is appropriate because the schema carries the parameter-documentation load.

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: get a Stripe management URL for portal, upgrade, or cancel. It also mentions the billing portal and that it returns a URL for the user to open. However, it omits the 'subscribe' action that the schema explicitly supports, so the full purpose is understated and it does not distinguish itself from sibling billing tools.

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

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

The description implies use for subscription management and billing-portal requests, but it does not provide explicit when-to-use guidance or alternatives such as invoice_list, top_up_credits, or credits_balance. It also gives no guidance about when to use 'subscribe' versus 'manage' beyond what the schema already states.

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

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

Annotations already indicate readOnlyHint=false and openWorldHint=true, which is consistent with a state-changing external payment action. The description adds valuable behavioral context by revealing the Stripe checkout flow and that the returned URL must be shared with the user for payment completion. 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 two short sentences, front-loads the primary action, and immediately provides the most important behavioral detail: the returned checkout URL and user handoff. Every sentence earns its place without redundancy.

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 covers the core action, the return value, and the follow-up user action. It does not mention potential issues like stripe session expiry or that credits are only credited after payment, but these are minor given the tool's simplicity.

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 fully documents amount_usd including minimum, maximum, and example values. The description only repeats the minimum $1 constraint and adds no new semantic meaning beyond what the schema already provides.

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 and resource: 'Add credits to your account.' It clearly distinguishes this tool from sibling read-only tools like credits_balance and credits_usage by stating it returns a Stripe checkout URL for payment.

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

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

The description implies the tool is for adding credits to the account, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. There is no direct alternative for adding credits among siblings, but the guidance remains implicit rather than explicit.

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

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

Annotations already indicate this is not read-only and not idempotent. The description adds meaningful behavioral context beyond annotations: long-running tools return a job_id to poll, brain_context errors require a brain_query round-trip, and backend/billing options affect execution. It does not contradict the annotations and adds useful operational detail.

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 every sentence earns its place. Critical routing rules are front-loaded with IMPORTANT and BRAIN markers, and the prose is structured around concrete workflows: discovery, invocation, long-running jobs, file handling, and brain_context resolution. There is 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?

Despite having no output schema, the description covers the full lifecycle an agent needs: how to discover catalogue tools, how to call them, what to do with job_id, how to handle local files, how to satisfy the brain_context gate, and how to route providers and billing. The parameter schema is fully self-documenting, so 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?

Schema description coverage is 100%, so the baseline is 3. The description goes further by clarifying that brain_context must be passed at the top level, not inside input, and by explaining how image-composition tools merge multiple file IDs into a single image_urls array. These are semantics not fully captured 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 opens with a specific verb and resource: 'Call a ToolRouter catalogue tool.' It clarifies the tool's role relative to discover, credits_balance, and other built-in tools by explicitly stating they are NOT catalogue tools and must never be called through use_tool. This clearly differentiates it from the sibling tools.

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

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

The description gives explicit when-to-use guidance: use discover first, then pass the tool name and skill. It also states when NOT to use the tool (built-in tools should be called directly), and names alternatives such as job_get for polling long-running jobs, file_write for hosting local files, and brain_query for brain_context. This is thorough routing guidance.

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