ToolRouter

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context by explaining what the detail view returns, including team members, role, subscription status, and related resource pointers.

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 compact sentences, front-loads the core capability, and immediately clarifies the two modes. There is no wasted wording.

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 no output schema, the description provides enough context to call it correctly. It covers both modes and summarizes the richer detail returned when a slug is supplied.

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 parameter is already documented. The description still adds value by explaining the semantic consequence of including versus omitting slug, rather than just repeating that it is an optional account slug.

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: list billing contexts or get detail on one. It clearly explains the two operating modes, but it does not explicitly distinguish itself from siblings such as account_switch 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?

It gives a clear condition for each mode: omit slug to list all accounts, provide slug for full detail. It does not name alternative tools or when not to use this one, so it stops short of 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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that write mode requires supplying fields, but says nothing about auth/permission needs or what a read returns. Adequate but thin given the lower bar annotations set.

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 compact sentences with the core purpose front-loaded and the mode-selection instruction second. Every sentence earns its place, though the action guidance mildly restates 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?

With no output schema, the description could say more about the return shape of a read, but the dual-mode semantics and full param documentation leave little an agent is missing. Annotations carry the safety profile, so overall coverage is solid.

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 all six parameters including the set-only fields and the enum. The description's mention of action values and field categories adds little beyond what the schema already provides, 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?

States a specific verb (read or write) and resource (billing preferences), and enumerates the fields covered (auto-reload, budget cap, default context). The purpose is unambiguous, though it makes no reference to any sibling tool to differentiate itself.

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 explains how to invoke each mode via the action parameter ("get" to read, "set" with fields to write), which implies usage. However it offers no when-not guidance, prerequisites, or alternatives among the account_* siblings.

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

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

The annotations declare readOnlyHint=true, yet the description claims the tool will 'Initialize' and 'provision' the account when needed, which are state-creating actions. That directly conflicts with a read-only declaration; the only mitigating context (idempotentHint=true) is already supplied by the annotations rather than by the description.

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, zero filler, with the imperative 'CALL THIS FIRST' front-loaded and the outcome ('return your user ID and plan') trailing it. Every clause carries selection-relevant information.

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

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

For a zero-parameter setup tool with no output schema, the description supplies the trigger conditions, the no-argument nature, and the return contents (user ID and plan). The remaining gap is behavioral: it does not reconcile its provisioning language with the read-only annotation, leaving the agent unsure whether the call mutates account state.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description usefully tells the agent that no argument is required and what identity/plan information comes back.

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

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

Specific verbs and resource: 'Initialize or re-check your account, provision it when needed, and return your user ID and plan.' An agent can tell this apart from account_list, account_switch and account_preferences without opening 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?

Explicit triggers are given ('CALL THIS FIRST when the user asks to set up ToolRouter, connect their account, check their account status, or get started'), which is strong routing guidance. It stops short of naming alternatives or exclusions, so the overlap with account_list for the 'check their account status' phrasing is left unresolved.

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 mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so safety is covered. The description usefully adds that this changes persistent global 'active billing context' state rather than a per-call parameter, but it does not say what happens on an invalid or unknown slug, nor whether the change persists across sessions.

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 the effect front-loaded before the accepted input formats, and no filler. The format examples partly duplicate the schema but stay brief enough to not be wasteful.

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 state-toggle tool with no output schema and full annotation coverage, the description gives an agent enough to call it correctly. Remaining gaps are minor: error behavior on bad input and confirmation of the resulting active 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 coverage is 100% and the single parameter is fully documented with the same slug/team-ID examples. The description adds no format, validation, or defaulting detail beyond what the schema already provides, 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?

States a specific verb and resource ('Set the active billing context'), which tells an agent exactly what changes. It is clearly distinguishable from siblings like account_list or account_setup, though it never explicitly names or contrasts those 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?

Usage is only implied: the agent infers this is the way to change which account subsequent billing operations apply to. There is no explicit when-to-use, no prerequisite (e.g. must the slug already exist), and no guidance on when account_setup or account_preferences is the better choice.

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=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: persisted knowledge becomes available to all future tool calls, which communicates the global side effect of a write. It doesn't discuss duplicate handling or error cases, keeping it below a 5.

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 waste, and the core action is front-loaded before the hierarchy detail. Every sentence earns its place by adding persistence and organisational context.

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

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

For a write tool with full schema coverage and no output schema, the description covers purpose, persistence effect, and the organisational model adequately. Minor gaps around edit-vs-create routing remain, but nothing critical for calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including enums for scope and load_tier. The description only gestures at wing/room/hall as organisational and adds no format or semantic detail beyond the schema, so baseline 3 applies.

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

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

The description clearly states the specific verb 'Create' and resource 'brain page', telling an agent exactly what operation it performs. It doesn't explicitly differentiate from siblings like brain_update or brain_admin, but the create-vs-modify distinction is reasonably inferable.

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

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

It implies when to use ('knowledge you add here') but offers no explicit when-not guidance or named alternatives such as brain_update for editing existing pages. The usage context is present but left to inference rather than spelled out.

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

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

Annotations already set readOnlyHint=false and destructiveHint=false, and the description usefully adds the team-admin authorization requirement plus the 3 AM local-time scheduling detail for team_sleep. However, it says nothing about the behavior or side effects of lint/link/promote/rebuild_index, which for a non-read-only, non-idempotent tool is a notable gap.

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

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

Three tight sentences, front-loaded with the tool purpose and then the action set. It is efficient, with only mild redundancy from re-listing the action enum that already lives in 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 five-action tool with no output schema, only team_sleep is fleshed out; the other four actions have no behavioral or outcome context. The role requirement and timezone semantics are helpful, but the definition is incomplete for the majority of its operations.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the sub_action enum and the IANA timezone default. The description mostly restates the sub_action values, adding little beyond what the schema fields already provide.

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?

"Brain admin operations" is an umbrella phrase, and while the description enumerates the five actions (lint, link, promote, rebuild_index, team_sleep), it explains none of them beyond their names. An agent cannot tell what "promote" or "link" actually do, and it is unclear how the "lint" action differs from the sibling tool brain_lint.

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?

Guidance is given only for team_sleep (which sub_action to pass, and that the Team admin role is required). No when-to-use context is offered for lint, link, promote, or rebuild_index, nor any routing versus the closely related brain_lint sibling.

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 idempotentHint=true, so safety/idempotency are covered. The description adds genuine value by disclosing the concrete consequence: the page disappears from searches and tool consultations. It stops short of describing reversibility or restoration.

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, zero filler, with the core action front-loaded and the consequence following. Nothing that could be trimmed.

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-param tool with full schema coverage and annotations covering the safety profile, the description supplies what it needs: the action and its effect. Minor gap is lack of reversibility/restore guidance, but no output schema is required for an archive.

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?

Only one parameter with 100% schema description coverage, so the schema already documents page_id fully. The description adds no syntax or format detail beyond the schema, which matches the baseline 3 for a single well-documented param.

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 (Archive) and resource (brain page), making the operation clear. However, it doesn't distinguish itself from close siblings like brain_update or brain_add, so an agent must infer whether 'archive' differs from 'update'.

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 when-to-use guidance or alternatives; it doesn't say whether to prefer brain_update for reversible edits or when archiving is the right choice. The use case is only implied by the effect sentence.

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?

Goes well beyond the annotations by disclosing that drawers contain original tool output redacted for credentials, that not all pages have drawers, and that drawers are a Step 4 feature for allowlisted tools only. The 404 failure mode and redaction security context are exactly the behavioral detail annotations cannot carry.

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

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

Three tight sentences, front-loaded with the core action, then the usage trigger, then the edge-case/availability caveat. Every sentence earns its place with no padding.

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

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

For a read-only single-param tool with no output schema, it covers the returned content (verbatim drawer text, redacted), the failure mode, and availability constraints. It stops short of describing the exact response shape or size of the returned source, which is a minor 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?

With a single parameter at 100% schema description coverage, the schema already documents page_id fully. The description references 'the page' but adds no syntax or format detail beyond the schema, so the baseline 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 a specific verb and resource: retrieve the verbatim source text (a 'drawer') linked from a brain page. It clearly distinguishes its scope (raw source) from the summary-oriented siblings like brain_query, so an agent can pick it without opening the 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?

Gives an explicit trigger condition: 'Use this when a summary lacks specifics you need.' It also notes the failure case (404 when no drawer exists) and the allowlist prerequisite. It stops short of naming an alternative tool when no drawer exists, so it is clear context without full 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, destructiveHint false, and openWorldHint false. The description adds that it finds stale pages, orphaned knowledge, and other issues, which is useful context about the diagnostic behavior and expected findings beyond the safety profile. It does not cover frequency or remediation, but with annotations covering safety, 4 is appropriate.

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?

Single sentence, front-loaded with the action and resource, then concrete examples. No wasted words.

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

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

For a zero-parameter, read-only diagnostic tool with rich annotations and no output schema, the description adequately explains what the tool does and what it looks for. It could specify whether the checks are advisory or whether it takes any action, but annotations already clarify read-only and idempotent behavior.

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

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

There are no parameters (0), so the baseline is 4 per rubric. The description does not need to explain 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?

States a specific verb ('Run maintenance checks') and resource ('your brain'), and enumerates the issues it surfaces (stale pages, orphaned knowledge). It does not explicitly distinguish itself from sibling tools like brain_status, so a 4 rather than 5.

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

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

The purpose implies when to use it (periodic maintenance/diagnostics), but there is no explicit when-to-use guidance, no alternatives named, and no exclusions. Implied usage only.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds ranking behavior and wing/hall narrowing, but omits temporal behavior (as_of) or pagination, so it adds moderate context 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?

Three sentences, front-loaded with purpose, then return behavior, then optional filtering. No redundant or filler text.

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 annotations covering safety, the description need not explain every parameter. It states the search purpose and return shape (ranked pages), which is sufficient for a read-only search tool, though it could mention the temporal as_of use case.

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 all seven parameters are documented in the schema. The description only restates wing/hall filtering with an example, adding little beyond the schema's own 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?

States a specific verb ('Search') and resource ('knowledge brain'), and explains it returns pages ranked by relevance. It does not differentiate from sibling tools like brain_expand or brain_wings, but the purpose is unmistakable.

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

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

No explicit when-to-use or alternatives are given. The description does not say when to use brain_query versus brain_expand for full text or brain_wings for browsing. Usage is implied only by the search phrasing.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the agent knows this mutates but is safe and repeatable. The description adds semantic context about what drawers_enabled actually does (stores raw tool output alongside summaries), which is genuine value beyond the annotations, but says nothing about permissions or side effects of toggling.

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 filler; the primary verb pair is front-loaded and the supported-setting detail follows immediately. Nothing needs to be cut.

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

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

There is no output schema, but the tool is small and low-risk, and the schema fully documents the three parameters including the enum and conditional requirements. The description covers what the tool does and the sole supported setting, leaving only minor gaps such as return shape for 'get' and whether more settings are planned.

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%, including the get/set enum and the note that value/setting are required only for 'set', so the schema carries the parameter burden and the baseline is 3. The description reinforces the single valid setting name but adds no syntax or format detail beyond the schema.

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

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

States a specific verb pair (view/toggle) and resource (brain settings) and names the one setting currently supported, with a parenthetical explaining what it does. It does not explicitly distinguish itself from adjacent siblings like brain_update or brain_admin, but the resource is clear enough that an agent can pick it without opening other schemas.

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

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

Usage is implied by the verb pair 'view and toggle' and the note that only drawers_enabled is currently supported, but there is no explicit when-to-use guidance or pointer to alternatives such as brain_update or brain_admin. An agent can infer intent but is not routed.

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 by structured data. The description adds useful scope context (personal AND team brain) and indicates the return content is page counts plus recent pages, which goes modestly 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?

A single tight sentence with the resource and scope front-loaded and no filler. Nothing could be removed without losing information.

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

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

With no parameters and no output schema, the description carries the burden of describing returns, and it does indicate the shape (page counts and recent pages). It stops short of details like how many recent pages or the exact format, but for a parameterless status tool this is 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?

The tool takes zero parameters, so the baseline is 4. There is no parameter surface the description needs to compensate for, and the schema coverage is reported at 100%.

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 ('View') and resource ('brain page counts and recent pages'), and scopes it to both personal and team brains. It is clear enough to distinguish from mutation siblings like brain_update or brain_delete, but it does not explicitly differentiate itself from read siblings such as brain_query 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?

There is no explicit when-to-use guidance and no named alternative. An agent can infer this is an at-a-glance status check, but nothing tells it when to prefer brain_status over brain_query for inspecting brain contents.

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 cover safety (readOnlyHint=false, idempotentHint=true) but say nothing about authorization. The description adds a real permission constraint — moving a page to team scope requires team admin role — which is valuable context beyond structured fields. It does not, however, clarify whether omitted fields are left untouched (patch semantics) or what the response looks like.

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

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

Three tight sentences with zero filler. The core mutation is front-loaded, followed by the re-file and scope use cases and the permission caveat — a well-ordered, information-dense payload.

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 mutation tool with no output schema, the description covers purpose, key use cases, and the critical team-scope authorization rule. The remaining gap is patch-vs-replace semantics for unmentioned fields and any confirmation of what is returned; these are secondary but not fully covered elsewhere.

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 goes beyond the schema by explaining the intent behind the groups of parameters: wing/room/hall perform re-filing, and scope moves a page between personal and team brains. That interpretive layer earns the bump above baseline.

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

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

States a specific verb ('Edit') and resource ('an existing brain page'), then enumerates the two facets it covers: content/metadata and re-filing (wing/room/hall/scope). This clearly separates it from brain_add, brain_delete, and brain_query among the 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?

Gives concrete when-to-use context, notably the scenario 'an auto-ingested page landed in the wrong place' for scope changes and the re-filing use case for wing/room/hall. It stops short of naming alternative tools (e.g., brain_delete for removal, brain_add for creation), so it does not reach the explicit alternatives bar.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the return shape (rooms, halls, page count, last-updated) and the scope relationship between wings and halls. It does not discuss pagination or whether unpopulated wings appear, but it goes meaningfully 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?

Three tightly packed sentences with zero filler, front-loading the definition, then the return contents, then the routing purpose. Sized appropriately for a simple no-argument list 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?

There is no output schema, so the description must convey the return shape, which it does (nested rooms/halls, page count, last-updated). For a one-optional-param read tool with full annotation coverage, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter include_team is fully documented in the schema, including default behavior. The description never mentions team-scope counting, so it adds nothing on parameters; baseline 3 applies when the schema does the work.

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 (list) and resource (wings) and defines the domain concept explicitly ('top-level areas your knowledge is organised under') with concrete examples. An agent can distinguish this enumerative tool from sibling brain_query or brain_status without opening the 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?

Explicitly names the downstream purpose and the alternative: 'Use this to discover the right wing/hall to pass to brain_query.' This tells the agent both when to call it and what the follow-up call is, leaving no inference required.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a non-idempotent write in a closed world. The description adds the mode taxonomy but says nothing about the OAuth interactive/redirect flow, duplicate-connection behavior, or credential storage implications, which are the behaviors an agent most needs here.

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, front-loaded with the core purpose followed immediately by the mode-specific parameter routing. Every clause carries information; there is no filler or repetition 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?

With 10 optional parameters, no required fields, and no output schema, the description covers the critical decision surface: which parameter set applies to which connector type. It omits what happens after invocation (e.g. whether OAuth returns a URL the user must visit) and any required-per-mode callouts, which would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine value the schema lacks: it groups parameters into coherent combinations per scenario (type+kind for OAuth, catalog_slug for catalog MCP, url+auth_type for custom MCP). It does not clarify billing, slug, or display_name usage, so it stops short of 5.

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 ("Connect a new OAuth account or MCP server") and enumerates the three connection modes, so an agent immediately understands the operation. It does not explicitly contrast itself with adjacent siblings like connector_remove, connector_list, or credential_save, which keeps it short of a 5.

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

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

It gives concrete branching guidance for each mode: OAuth uses type+kind, catalog MCP uses catalog_slug, custom MCP uses url+auth_type. That is clear selection context, but there are no exclusions or explicit "use this instead of X" statements (e.g. versus credential_save for plain API keys).

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 safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the agent knows this is a safe idempotent read. The description adds modal detail (summary vs detail, that detail exposes every tool the connector exposes), but says nothing about return format or pagination for a list operation.

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

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

Front-loaded with the core purpose, then parameter guidance, in three tight sentences with no filler. The density is high but every clause about slug, type, and include_available 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 read-only list tool with full schema coverage and strong annotations, and no output schema to explain, the description covers the relevant modes and modifiers an agent needs. It omits mention of the context scope param and any return-shape hints, but these are minor given the structured fields.

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 all four parameters (slug, type, context, include_available) are already documented in the schema; baseline 3 applies. The description largely restates that coverage, adding only marginal value such as noting the detail view lists every exposed 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?

States a specific verb (List) and resource (connected accounts and MCP servers), and explicitly distinguishes its two modes: summary listing versus detail for one connector. An agent can tell this apart from siblings like connector_add, connector_remove, and connector_permissions without opening a 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?

Clearly explains how to select behavior: pass slug for detail, type to filter, include_available to broaden scope. There is no explicit statement of when NOT to use it or which sibling to prefer for adjacent tasks (e.g. permissions vs listing), so it falls short of full 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?

With annotations supplied (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description correctly frames the tool as a view/mutate hybrid and adds the admin-role authorization requirement for team scope, which annotations do not cover. It does not describe reversibility of a 'set' or what happens to overlapping rules, leaving some mutation behavior unstated.

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

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

Three tight sentences, front-loaded with the purpose and its scope, followed by the two-mode workflow and the one prerequisite. The em-dash enumeration adds information density with no filler. Nothing could be cut without losing 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 15-parameter mutation tool with no output schema and only one required field, the description covers purpose, both operating modes, the slug source, and the authorization gate. It is slightly thin on what a 'list' returns and the side-effects of a partial 'set', which matters more here because no output schema exists to fill that 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 description coverage is 100%, so every one of the 15 parameters is already documented (including the 'for set' qualifiers and the '*' wildcard). The description's parameter content largely restates the action enum and the tool_name+rules combination; the only genuine addition is the '(from connector_list)' cross-reference, which justifies staying at the high-coverage baseline rather than above it.

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 gives a specific verb pair (view or set) and resource (permissions for tools on a connected MCP server), then enumerates exactly what those permissions cover: allowed tools, rate limits, budget caps, argument restrictions. It even names the sibling (connector_list) as the source of the slug, so an agent can place it in the toolset without opening a 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?

It clearly distinguishes the two modes and their triggers: action:"list" to see current rules, action:"set" with tool_name + rules to update one. It also states the prerequisite that team scope requires admin role and points to connector_list for the slug. No explicit 'when-not-to-use' beyond that, 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no note on whether credentials/tokens are revoked, whether the action is recoverable, or what scope (personal vs team) it affects.

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 very short sentences with the action front-loaded and zero padding. It is efficient, though the terseness borders on under-specification rather than exemplary conciseness.

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 mutation with no output schema, the annotations carry the safety information, and the schema covers all three parameters. However, the description says nothing about side effects (credential removal, team-scope resolution via billing), leaving meaningful gaps for a disconnect 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 slug, type, and billing are already fully documented in the schema. 'Pass slug' merely echoes the required parameter and adds no syntax, format, or interaction detail, making the baseline 3 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 a specific verb and resource ('Disconnect a connector') that cleanly separates it from sibling connector_add and connector_list. It does not explicitly name those siblings or the scope of what gets disconnected, so it falls short of a 5.

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

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

The only guidance is 'Pass slug' — a restatement of the required parameter. There is no when-to-use, when-not-to-use, prerequisite, or alternative (e.g. connector_permissions, credential_delete) mentioned, leaving the agent to infer 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=false, idempotentHint=true and destructiveHint=false, so the safety and repeatability profile is covered. The description adds one genuine behavioral constraint (the credential must be multi-value), but says nothing about what happens to the previously-default entry or about personal vs team scope effects.

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

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

A single short sentence that front-loads the action and the object. Nothing is padded and nothing extraneous is included.

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 3-parameter mutation with no output schema and full schema coverage, the definition is minimally sufficient. It is missing any note on whether the prior default is replaced or how the result is confirmed, which would matter in a multi-credential workflow.

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 examples and the personal/team context documented in the schema itself. The description adds no syntax, format, or edge-case meaning beyond what the schema already provides, so the baseline 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?

The description names a specific verb ('Set') and resource ('default value for a multi-value credential'), and the qualifier 'multi-value' narrows scope usefully. It does not, however, distinguish itself from siblings like credential_save or credential_list, which an agent must infer on its own.

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 statement of when to use this versus credential_save or credential_delete, and no prerequisites beyond the implicit 'credential must be multi-value'. The agent gets a purpose but no routing guidance among the many credential_* siblings.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the high-value disclosure that omitting label deletes ALL entries for the name — a blast-radius detail essential for a destructive 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?

Three short sentences, zero waste, with the destructive scope condition placed immediately after the core action.

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 3-parameter destructive tool with no output schema, the description covers the action and the riskiest parameter interaction. The context parameter (personal vs team) is left entirely to the schema, which is a minor 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 description coverage is 100%, and the schema itself already states 'Omit to remove all entries for this credential name.' The description's label semantics are largely redundant with the schema, 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?

States a specific verb (remove) and resource (saved credential), and immediately clarifies the conditional scope of deletion. An agent can distinguish this from credential_save and credential_list without opening 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?

The description explains the internal branching (label present vs absent) but never states when to reach for this tool versus credential_save, credential_default, or credential_list. Usage is implied by the verb rather than explicitly guided.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns setup instructions, an informational output, but does not disclose format, permissions, or other behavioral context beyond that.

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

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

It is a single, front-loaded sentence with no redundant or filler content. For a simple lookup tool, this is appropriately sized.

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 one required, fully described parameter, rich annotations, and no output schema, the description covers the essentials: what the tool does and what it returns. It is somewhat thin on sibling differentiation, but complete enough 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?

Schema description coverage is 100%, and the single 'name' parameter is fully documented with credential examples in the schema. The description only reiterates that the credential is 'specific,' adding no syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: 'Get setup instructions' for a credential. This clearly distinguishes it from sibling tools that save, delete, list, or set defaults, but it does not explicitly name any 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 description gives no explicit when-to-use guidance or conditions for choosing this tool over siblings like credential_list, credential_save, or credential_default. Usage is only weakly implied by the phrase 'setup instructions.'

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the summary-vs-detail and catalog-expansion behavior, but does not describe permissions, return shape, or pagination.

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 core listing purpose and then the invocation details. There is no wasted language.

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/detail tool with rich annotations, complete schema coverage, and no output schema, the description covers the main modes sufficiently. The only omission is explicit mention of the context parameter, but the schema handles it.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including context. The description reinforces name and show_available semantics but omits context and adds little beyond the schema's own 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 a specific verb and resource: listing saved credentials, with a detail variant. It distinguishes list behavior from mutation siblings like credential_save and credential_delete, but it does not explicitly name alternative tools such as credential_guide or credential_default.

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 clearly explains how to switch between summary and detail views by passing name, and how to expand to the full catalog with show_available: true. It lacks explicit when-not-use guidance or named alternatives, but the invocation context 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuine behavioral context beyond that: keys persist across sessions and are applied automatically. It omits overwrite/upsert behavior and any auth requirements, so it is useful 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?

Two short sentences with zero filler; the persistence/auto-use behavior is front-loaded after the core purpose. Slightly terse rather than padded, which is the right failure mode, though it leaves room for one more clarifying clause.

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 5-param mutation with full schema coverage and no output schema, the description is adequate but thin. It conveys persistence and automatic usage, yet says nothing about overwrite semantics, team-context sharing effects, or how defaults interact with existing values — all relevant for a save 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 all five parameters are fully documented in the schema (including the label-multiplicity rule and the context default). The description adds no parameter-level meaning beyond that, 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?

States a specific verb (Save) and resource (credential), with a clarifying parenthetical that this is a BYOK provider API key, which distinguishes it from the broader credential_* family. It does not explicitly say how it differs from credential_default or credential_delete, so it falls short of full sibling differentiation.

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

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

The description says what the tool does but never states when to use it versus credential_default (for setting defaults) or credential_guide (for guidance). No prerequisites, no exclusions, no alternatives named. Usage can only be inferred from the word 'Save'.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral content by naming the returned fields, including the non-obvious negative-balance warning behavior — valuable since there is no output 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?

A single sentence with no wasted words; the highest-value content (what is returned) is front-loaded. Nothing to trim.

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

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

With no output schema, the description carries the burden of describing return values, and it does so adequately. It stops short of clarifying what 'active context' resolves to or whether results are cached, but for a zero-param read call this is close to 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?

There are zero parameters, so the baseline is 4. The description's 'for the active context' adds meaning about how the tool resolves which account it reports on without requiring an argument.

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 enumerates exactly what the tool returns — current balance, plan tier, rate limits, and negative-balance warnings — which is a precise purpose for a zero-argument read tool. It does not, however, explicitly distinguish itself from the sibling credits_usage or top_up_credits, so an agent must infer the boundary.

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 when-to-use statement and no reference to any alternative tool. The phrase 'for the active context' implies the ambient account scope but gives no guidance on when an agent should call this versus credits_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 this a safe read (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so safety is covered. The description adds genuinely useful output behavior ('sorted by cost', '_others rollup') that isn't in the schema. It stops short of describing the return shape or how the summary vs history modes differ beyond pagination.

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 padding, and the core purpose is front-loaded. The telegraphic style ('Pass scope: "me" | "team"') is efficient though it duplicates schema enum info.

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, zero-required-param tool with a fully documented schema, the description is adequate but leaves gaps: no clarification of the summary-vs-history distinction, no return-shape note (no output schema exists), and no sibling routing to credits_balance or invoice_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 all five parameters are already documented, including all three enums and the period window. The description mostly restates the scope/detail enums already in the schema; it only adds the '_others rollup' meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description identifies the resource (usage summary/history for credits) and adds two behavioral facts ('sorted by cost', '_others rollup'). However it never distinguishes itself from the sibling credits_balance (or invoice_list), which an agent could easily pick by mistake. Clear resource, no sibling differentiation.

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

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

It mentions 'summary or history' but never states when to use one mode vs the other, nor when to prefer this over credits_balance. The only hint at a trigger ('history mode') appears in the offset parameter, not the description. No when-to-use guidance beyond implied 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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context beyond structured fields: the response includes a top-level `connectors` array of the user's connected SaaS accounts, with an example of how to use it. It does not discuss pagination or result limits, keeping it at a 4.

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

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

Front-loads the purpose and then the routing flow. It is somewhat dense and repeats the category list already in the schema enum, which is minor redundancy, but every sentence is otherwise informative.

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?

No output schema exists, so the description carries the return-value burden and does so by explaining the `connectors` array and that exact-name queries return schemas. Combined with annotations covering safety and the 100%-covered input schema, an agent has what it needs; only return format details are thin.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by clarifying query semantics the schema does not: an exact tool name (e.g. "seo") returns full schemas and examples, and it supplies natural-language query examples plus the category list, adding real 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?

States a specific verb and resource: "Find the right ToolRouter tool for your task." It distinguishes itself from siblings by naming route and use_tool and explaining its distinct role (schemas/listing) in the flow.

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

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

Explicit routing guidance: "prefer route({ intent }) to pick and run a tool. Use discover when you need schemas or a listing, then call use_tool(tool, skill, input)." This names the alternatives and the exact conditions that select each, leaving nothing 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?

Goes well beyond the annotations (which only state this is a non-read-only, non-idempotent write) by disclosing the retention/review SLA ("stored and reviewed within hours"), a hard rate limit ("5 reports per hour"), and an explicit data-handling contract listing what must and must not be included. These are exactly the behavioral traits annotations cannot 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?

Front-loads the trigger condition, then requirements, then exclusions and limits, so each sentence contributes. It is somewhat long, and the no-secrets/no-chat-history list is duplicated between the body and the interaction_log parameter description, which is minor 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 10-parameter write tool with no output schema, the definition covers everything an agent needs: when to file, what evidence to attach, what to redact, throughput limits, and that no synchronous return value is expected. Nothing material is left unspecified.

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 and the schema already carries field-level meaning. The description adds value by prescribing the content for the key fields — relevant ToolRouter errors, all call IDs, non-sensitive input shape, retries, expected behavior — guiding the agent on what to populate rather than just restating field names.

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?

Uses a specific verb+resource ("Report a ToolRouter platform bug") and scopes it to failures that block the user's task, so the agent can tell this apart from generic feedback tools. It never names the closest siblings (feedback_request_tool, feedback_review), so the differentiation is implied rather than explicit.

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 positive triggers ("tool crashed, returned malformed data, timed out, behaved inconsistently") and explicit exclusions ("Skip this for expected errors like invalid input, missing credentials, insufficient balance, rate limits, or genuine not found results"). This is a textbook when/when-not specification.

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 a non-read-only, non-destructive write, but the description adds crucial behavioral context beyond them: requests go straight to the team, there is a 5-per-hour rate limit, and personal data/API keys/secrets must be omitted.

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 sentences, front-loaded with purpose, then usage trigger, then two brief constraints. Every sentence adds distinct information with no filler.

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

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

For a submission tool with no output schema, the description covers purpose, trigger, destination, and constraints. Given the rich schema and annotations, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds guidance for the 'what' parameter ('describe the capability in plain terms') and a data-handling constraint applicable across parameters, lifting it slightly above baseline.

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

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

States a specific verb and resource: 'Ask ToolRouter to build a tool that does not exist yet.' Clearly distinguishes from siblings like discover by framing it as the fallback when discovery fails.

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 names the trigger: 'Use this when discover returned nothing useful for what the user needs.' Names the alternative (discover) and the condition that selects this tool, leaving no inference needed.

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 that this is a non-read-only, idempotent, non-destructive operation. The description adds no behavioral context beyond restating the basic action, such as where the review goes, whether it is public, or whether authentication is required.

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. Its brevity is appropriate, though it could be slightly more structured by including one usage cue.

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

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

The tool is simple, the schema is fully described, and annotations cover the mutation and idempotency profile. However, the description does not explain when to use this feedback tool instead of sibling feedback tools, leaving a contextual 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 description coverage is 100%, so the input schema fully documents the tool, rating, and optional review fields. The description mentions star rating but adds no 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: submitting a review or star rating. It is clear what the tool does, but it does not distinguish itself from nearby feedback tools such as feedback_request_tool or feedback_debug.

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 on when to use this tool versus alternatives like feedback_request_tool or feedback_debug. It also omits any prerequisites or context for submitting feedback.

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 idempotentHint=false, so the bar is lower, yet the description still adds real value: irreversibility ('Cannot be undone') and an authorization prerequisite for team files. It does not cover side effects on references or shared links, keeping it below a 5.

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, zero filler, with the destructive consequence front-loaded ahead of the conditional permission note. Every sentence carries information an agent needs.

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 destructive tool with full annotation coverage and no output schema, the description supplies the two facts that matter most: irreversibility and role requirements. Minor gaps remain — no mention of what happens to dependent resources or whether deletion is soft/hard.

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 file_id parameter, so the baseline of 3 applies. The description adds no format, source, or lookup guidance for obtaining a valid file_id, so it contributes nothing beyond the schema.

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

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

The verb+resource pair ('Delete a file') is specific and unambiguous, and the scope note about team files clarifies the operation's breadth. However, it never names or contrasts with siblings such as file_write or file_read, so an agent gets no explicit routing help beyond the obvious verb difference.

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 only implied by the verb, plus one precondition ('For team files: requires owner/admin role'). There is no statement of when to prefer this over file_write/update paths, nor any warning about when deletion should be avoided — guidance is adequate but thin.

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, so the safety profile is covered. The description usefully adds that query switches the tool into semantic-search mode and that cursor enables pagination, but it says nothing about result volume, ordering, or what the payload contains.

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 with no filler; the mode-switching behavior comes first, which is the most decision-relevant fact. Only nit is the minor mislabel of "cursor" as a filter.

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 tool with no output schema and a fully documented schema, the description is adequate but thin: it neither explains the pagination contract nor the personal/team context switch, leaving the agent to read the schema for anything beyond the list/search distinction.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including enums and defaults. The description merely re-lists a subset (section, tags, plan_status, limit, cursor) and omits context and prompt_type, adding almost nothing beyond the structured fields.

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 (list/search) and resource (files), and clearly distinguishes the two modes: browse by default, semantic search when query is present. It does not, however, differentiate itself from file_read or the other *_list siblings, so it stops short of a 5.

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

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

"Optional query triggers semantic search" gives a genuine when-to-use signal for the search mode, and the filter list hints at narrowing. But there is no guidance on when to prefer file_read over this, when search is a poor fit, or how the context/team scoping 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: text returns inline while binary returns a download URL, which tells the agent what to expect from the call.

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 tight sentences, front-loaded with the primary behavior and then the return-mode distinction. Every sentence earns its place with no filler.

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

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

With no output schema, the description must convey return behavior, and it does so succinctly for both text and binary cases. It leaves error handling (e.g., missing/invalid file_id) unaddressed, but the essentials for correct invocation are present.

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

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

Schema coverage is 100% and the file_id parameter already includes a format example, so the schema carries the burden. The description adds no further meaning to the parameter itself, matching 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 (Read) and resource (a file's full content), clearly distinguishing it from siblings like file_list and file_write. It does not explicitly name those alternatives, but the action 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?

Usage is implied by the verb and the file_id requirement, but there is no explicit when-to-use guidance and no mention of alternatives (e.g., file_list to enumerate IDs first). Adequate but with clear gaps.

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 this as a non-read-only, non-destructive, non-idempotent write operation, so the safety bar is lower. The description adds a useful multi-step binary upload workflow, but it references a "binary: true" parameter that does not exist in the input schema, reducing reliability.

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, front-loads the main purpose, and then covers mode usage. It is appropriately sized, though the mention of an undefined binary parameter weakens the 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?

For a 16-parameter tool with nested objects and multiple upload paths, the description only covers text create/update and binary upload, omitting asset retrieval and image URL/data alternatives. The rich input schema compensates, but the description is still incomplete enough to require schema reading.

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 carries the parameter documentation burden. The description mostly repeats the mode enum and adds a binary workflow involving a parameter absent from the schema, so it does not add meaningful semantic value beyond structured fields.

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: "Create or update a file." It implies creation/update rather than read/delete/list, but does not explicitly name sibling tools or otherwise differentiate itself 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?

It explains the create/update modes and a binary finalize workflow, but gives no explicit when-to-use guidance versus alternatives or when not to use this tool. Usage is implied by the create/update framing.

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, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds only one behavioral detail, that results are scoped to the 'active billing context', which is useful but not elaborated (what defines the active context, what happens if none is set).

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, front-loaded with the verb and resource and free of padding. It is arguably terse rather than optimally sized, but there is no wasted text.

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, annotated, zero-required-param read tool this is roughly adequate, and the absence of an output schema means return values need not be explained. Still, 'active billing context' is left undefined and there is no note on pagination or whether an account switch affects the result set.

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 single 'limit' parameter is fully documented with default and max in the schema. The description contributes nothing about this parameter, which is acceptable given the schema already carries it, but no added meaning is provided.

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 ('List') and resource ('invoices'), which is clear. However, it offers no differentiation from adjacent billing siblings such as credits_usage or subscription_manage, so an agent must infer that this tool is invoice-specific by name alone.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternative tools for related billing data. The agent gets a statement of what the tool returns but nothing about the conditions under which it 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the 'running' scope qualifier, implying finished jobs cannot be cancelled, but says nothing about permissions, whether partial output is discarded, or what state the job ends in.

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 no filler. It is arguably too terse for a mutation, but nothing in it is wasted or buried.

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

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

For a one-parameter mutation with rich annotations and no output schema, the essentials are present. Still missing meaningful context: whether cancellation is irreversible, what the caller should do if the job already completed, and whether the response confirms termination.

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 single job_id parameter is fully documented in the schema. The description adds no format, ID-origin, or validation detail beyond what the schema already provides, 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?

Specific verb+resource: 'Cancel' + 'a running job', which cleanly separates it from job_get and job_list in the sibling set. It is clear but bare - no mention of what a cancel actually does (terminate, abort, mark stopped).

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 when-to-use or when-not-to-use guidance. It never states that the job must be in a running state, nor what to do for an already-finished job (check with job_get first?), leaving the agent to infer.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine behavioral context beyond that: the exact status values (running | completed | failed), that result is only present in a terminal state, and the polling loop expectation.

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 purpose and immediately followed by return semantics and the polling instruction. No filler; 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?

With no output schema, the description shoulders the return-value burden and does so by naming the status enum and when result appears. It omits the shape of 'result' itself, which would have made it fully self-sufficient, but for a polling tool it is largely 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% and the single job_id parameter is fully documented in the schema ('returned when a long-running tool was called'). The description adds no syntax or format detail beyond what the schema already provides, 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?

States a specific verb (Get) and resource (job), and further specifies what it returns: status and result. It is clearly distinguishable from sibling job_list (enumerate jobs) and job_cancel (cancel a job) by describing retrieval of a single job's status/result.

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 operational guidance: 'Keep polling until you get a terminal status,' which tells the agent when and how to call it repeatedly. It stops short of naming alternatives (e.g., job_list or job_cancel) or when-not-to-use conditions, so it lands just below the top.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a modest scope hint ('active and recent') but says nothing about pagination behavior, ordering, or what the default return window is, leaving gaps beyond the structured hints.

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, zero filler, with the object of the operation front-loaded before the optional filter detail. 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 a simple, parameterless-required list tool with full schema coverage, rich annotations, and no output schema, the description is adequate to call the tool correctly. It could note pagination or result ordering, but 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 coverage is 100%, so both parameters (limit with default/max, status enum) are fully documented in the schema; the baseline is 3. The description only echoes the status filter ('Optional status filter') and adds no syntax, default, or interaction detail for limit.

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

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

Specific verb ('List') plus resource ('jobs') with a scope qualifier ('active and recent'), which lets an agent distinguish it from job_get and job_cancel. It does not name those siblings explicitly, so sibling differentiation is implied rather than stated.

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 'Optional status filter' implies when the filter is useful, but there is no explicit guidance on when to use this list tool versus job_get for a single job, nor any mention of exclusions. Usage is inferable but not spelled out.

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

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

The description adds critical behavioral context beyond the annotations: the secret is returned only once and must be saved immediately. Annotations already declare this is a non-read-only, non-idempotent, non-destructive operation, so the description's warning about one-time secret exposure is the key additional disclosure. It does not mention rate limits or duplicate-name behavior, but the one-time-secret detail is materially useful.

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

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

The description is two short sentences with zero wasted words. The core action is front-loaded, and the critical operational warning follows 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 one-parameter creation tool with clear annotations and no output schema, the description covers the essential behavior an agent needs: it creates a key and returns the secret only once, making the immediate-save requirement explicit. Nothing critical 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?

Schema description coverage is 100%, and the single parameter 'name' is fully documented in the schema with an example. The description adds no further parameter semantics beyond what the schema already provides, so the baseline score 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: 'Create a new API key.' It clearly distinguishes this action from sibling tools such as key_list and key_delete, which respectively list and delete API keys. An agent can identify the tool's purpose without opening the 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?

The description explains how to handle the result ('save it immediately') but gives no guidance on when to use this tool versus alternatives like key_list or credential_save. It does not state conditions, prerequisites, or exclusions, leaving usage context to inference from the tool 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 idempotentHint=true, so the safety profile is covered. The description adds a genuinely useful constraint not present in the annotations: it refuses to revoke the currently-authenticating key, which changes agent behavior. It could go further on consequences (e.g., whether revoked keys are recoverable).

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, zero filler, with the core action stated first and the important constraint second. Nothing is wasted or buried.

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

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

For a one-parameter, no-output-schema tool whose annotations already carry destructiveness and idempotency, the description covers the essentials plus a key behavioral guard. The main remaining gap is what happens on failure or whether revocation is reversible.

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

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

With a single parameter at 100% schema description coverage, the schema already documents key_id and its origin (key_list). The description adds no additional meaning about the parameter, 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 uses a specific verb ("Revoke") plus resource ("an API key"), so an agent immediately knows this is a deletion operation. It is clearly distinguishable from siblings like key_create and key_list, but it does not explicitly contrast itself with 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: revoke a key you no longer want, using a key_id that the schema notes comes from key_list. There is no explicit when-to-use/when-not guidance or statement of alternatives, and no mention of whether revocation is permanent or recoverable beyond the self-key exclusion.

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 by structured data. The description adds only the summary-vs-detail distinction, which is modest additional context; it says nothing about return contents (e.g., whether secrets are masked) or pagination.

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 tight sentences with zero filler, and the dual-mode distinction is front-loaded so an agent grasps the behavior 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 simple one-parameter read tool with rich annotations and no output schema, the description covers the essential behavior. It could note that key secrets are not exposed in the summary, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter's schema text ("Key ID for detail view. Omit to list all.") already documents its meaning fully. The description merely restates that same instruction, adding no syntax, format, or edge-case detail beyond the schema.

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

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

States specific verb (List) and resource (API keys), and clearly distinguishes two modes: summary listing versus single-key detail. It does not differentiate from siblings like key_create or key_delete, but the core operation 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?

"Pass key_id for detail view. Omit to list all." gives a clear conditional for the two modes, which is genuinely useful usage guidance. However, it offers no guidance about when to reach for this tool versus sibling key tools (key_create, key_delete) or other list tools.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description contributes nothing beyond that - no note on result scope, pagination, or what "outfits" means here - so it fails to add the extra context expected when annotations carry the baseline.

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, front-loaded sentence with no filler, which is structurally fine. However, the brevity comes from omission rather than economy - the sentence is under-specified for a tool with a scoping parameter.

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

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

This is a simple read-only list operation with full annotation coverage, 100% schema coverage on its one optional parameter, and no output schema, so the burden on the description is low. Still, it never clarifies whether the context parameter changes results or what the listing contains, leaving the agent with a minimally viable definition.

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 there is a single optional 'context' parameter whose schema description already spells out "personal" (default) or "team:<id>". The description adds nothing about this parameter, so the baseline 3 for schema-covered parameters 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 is essentially the title restated: the tool is named outfit_list, titled "List Outfits", and described as "List your outfits." It states a verb and resource but adds no information an agent did not already have from the name/title, and gives no scope (personal vs team) or differentiation from the many other *_list 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?

There is no when-to-use guidance, no mention of alternatives (scene_list, persona_list, product_list, connector_list, etc.), and no conditions under which this tool should be preferred or avoided. The agent must infer everything from the 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no return shape, no ordering, no note about what 'personal' vs 'team' context yields — so credit beyond the annotation baseline is minimal.

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 short sentence with zero padding and the key resource front-loaded. It is efficient, though its brevity shades into under-specification rather than tight precision.

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, zero-required-param list tool with full schema coverage and clear annotations, the essentials are present. It stops short of describing scope of results or how the context parameter changes the output, which leaves a small gap given there is no 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 single 'context' parameter is fully documented with its default and 'team:<id>' format in the schema itself. The description adds no syntax or semantics beyond what the schema already provides, so the baseline 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 a clear verb ('List') and resource ('personas'), so an agent immediately knows the operation. However, it offers no differentiation from siblings such as outfit_list, scene_list, or file_list beyond the resource noun, and does not hint at scope (personal vs. team) even though that is the tool's distinguishing parameter.

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 when-to-use guidance, no mention of alternatives, and no conditions or prerequisites stated. The phrase 'your personas' implies a scoped retrieval but never tells the agent when this tool is the right choice versus the other list tools.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing further — no pagination, scope, ordering, or result-size context — even though the lower bar from annotations still invites some added value.

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 short sentence with zero waste and the key verb front-loaded. It is appropriately sized, though its brevity borders on under-specification rather than true concision.

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 no output schema and one optional parameter, the description still leaves the agent without knowing what a 'product' is here or what the default scope returns. The agent can call it, but cannot anticipate the result set or choose context sensibly.

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 single optional 'context' parameter is documented in the schema as 'personal' (default) or 'team:<id>'. The description contributes no additional meaning, 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 states a verb (list) and resource (products), so it is not a pure tautology, but it adds essentially nothing beyond the title 'List Products' and does not distinguish itself from other *_list siblings in the family.

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 indication of when to use this tool versus the many other list tools available, and no prerequisites or context conditions are mentioned. The context parameter's personal/team distinction is left entirely to the schema.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is partly covered. The description adds meaningful behavior beyond that: it may either execute the call itself or return a payload, it will not override explicit values, and it degrades to candidate lists on low confidence. Missing details like cost/side-effect specifics (max_cost behavior lives only in 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?

Front-loaded with the core purpose, followed by the no-override guarantee and the routing flow. Slightly redundant ('fills only the blanks' and 'explicit values are never overridden' overlap) and dense, but every clause contributes to 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 carries the return contract and does so: it explains both outcomes (executed result vs ready-to-run payload) and the candidate fallback. For an open-world, executing router with nested input this is nearly complete, though edge cases like error behavior are unstated.

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 the governing rule that only blanks are filled and explicit values win, which clarifies how tool/skill/model/input interact. It adds modest semantic value over the schema descriptions, most of which already say 'honoured verbatim when set.'

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 behavior: send a natural-language intent, fill only the blanks, then execute or return a use_tool payload. It explicitly distinguishes itself from the sibling use_tool by describing the division of labor between the two. An agent can tell route apart from use_tool directly from the text.

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 an explicit decision flow: 'route → if confident and complete, result is returned; otherwise use the pre-filled call with use_tool.' It also states the condition for returning candidates (low confidence or no tool fits) and reinforces that explicit values are never overridden. The alternative and its selection condition are named, not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered by structured data. The description adds nothing beyond that—no detail on scope, default team vs personal resolution, or result size.

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, front-loaded sentence with no redundancy, which is efficient. However, its brevity stems from under-specification rather than disciplined editing, so it is only minimally adequate.

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 list tool with no output schema, the agent gets no information about the shape of returned scenes, ordering, or pagination behavior. The definition is technically callable but leaves real gaps.

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

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

Schema coverage is 100% and the single 'context' parameter is fully documented in the schema ('personal' default or 'team:<id>'). The description adds no parameter meaning, so the baseline 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?

The description 'List your scenes.' merely restates the tool name and title 'List Scenes' without adding scope, filtering, or domain specifics. It does nothing to separate this tool from siblings like outfit_list, persona_list, or file_list.

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 indication of when to use this versus the many other *_list tools, nor any prerequisites or context about what a 'scene' is in this product. The agent must infer everything from the 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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description's genuine addition is disclosing the return value — a URL the user opens — which matters because there is no output schema. It omits, however, that each call likely generates a fresh external Stripe session and says nothing about 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?

Two tight sentences with the return value front-loaded. The second sentence ('Also covers billing portal') partly restates the first sentence's 'portal' mention, so it is efficient but not perfectly lean.

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 2-parameter, no-output-schema tool whose annotations cover safety, the description is adequate but thin: it does not explain the action modes, whether the URL is single-use or time-limited, or what happens on re-invocation. Nothing is misleading, but meaningful behavioral context is left uncovered.

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 both parameters are enum-documented, so the baseline is 3. The description's 'portal, upgrade, or cancel' phrasing does not map cleanly onto the actual enum values ('subscribe'/'manage') and adds little beyond the schema.

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

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

The description states a concrete verb and resource — 'Get a Stripe management URL' — and enumerates the intents it serves (portal, upgrade, cancel). It is clear what the tool produces, though it does not contrast itself with any sibling tool by name.

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

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

'Returns the URL for the user to open' implies the usage context (hand a link to the user rather than performing the change server-side). However, there is no explicit when/when-not guidance, no mention of prerequisites (e.g., an existing subscription is needed for 'manage'), and no named alternative.

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 declare a non-read-only, open-world, non-idempotent write, and the description adds genuinely new context: the call does not itself complete payment, it returns a checkout URL that the agent must surface to the user, implying repeated calls create new sessions. It omits auth/permission requirements and any rate limits.

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 tight sentences, front-loaded with the action, then the critical behavioral detail (returns a URL) and the constraint. 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 single-parameter tool with no output schema, the description covers what an agent needs: the mutation, the indirect completion path, and the amount bound. The return value is explained even though no output schema exists.

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 amount_usd's type, minimum, maximum and examples already documented in the schema. The description's 'Minimum $1' merely repeats the schema's stated minimum, adding no new semantics. Baseline 3 applies.

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

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

States a specific verb and resource ('Add credits to your account') and immediately characterizes the outcome as a Stripe checkout URL, which is unmistakably distinct from the read-only siblings credits_balance and credits_usage. It never names a sibling explicitly, so it stops short of full differentiation.

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

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

The description implies the flow ('share it with the user to complete payment'), which tells the agent this is a hand-off step rather than a completed transaction. It gives no explicit when-to-use/when-not guidance or contrast with alternatives such as subscription_manage or invoice_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 only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds substantial non-annotation behavior: long-running calls return job_id to poll via job_get, brain-gated tools error and require brain_query output re-passed as brain_context, built-in tools must be invoked directly, and local files must be hosted via file_write before use.

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?

Information-dense and largely front-loaded: the core action and the route/discover alternatives come first, followed by caveats. It is long, but for a 7-parameter gateway tool most sentences carry distinct routing, error-recovery, or precondition content rather than 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 high-complexity dispatcher with 7 params, nested objects, open-world access and no output schema, the description covers alternatives, error recovery (brain_context, job polling), preconditions (file hosting) and exclusion rules. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents tool, skill, input, backend, billing, brain_context and response_format. The description reinforces the critical top-level placement of brain_context and notes the max-4 image merge default, but it mostly restates what the schema already carries. Baseline 3 applies.

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

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

States a specific action on a specific resource: dispatch a ToolRouter catalogue tool by name and skill. It explicitly draws the boundary against siblings, naming discover, route, credits_balance as NOT catalogue tools that must be called directly. An agent can distinguish use_tool from route/discover without opening the 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?

Gives explicit routing guidance: prefer route when tool+skill are unknown, use discover to obtain schemas/listing first, and call use_tool only with exact tool and skill names. It also covers the job_id polling path, the file_write prerequisite for image/file URLs, and the brain_query prerequisite when a brain_context error is returned.

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