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

With no annotations, the description fully explains the tool's behavior: returns `requires_key`, `connected`, and a `connect` block with signup URL and steps. It also details the decision flow and how the key is reused on future `execute` calls, giving the agent a complete mental model without needing annotations.

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

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

The description is reasonably sized given the behavioral detail it conveys. It is front-loaded with the core purpose, then flows into return values and decision logic. The line breaks and bold formatting improve readability. Every sentence contributes to understanding how and when to use the tool.

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

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

Despite having a single parameter and no output schema or annotations, the description covers all essential aspects: when to call, what is returned, how to interpret the results, and what actions to take next. It even mentions key reuse and the free-tool case, making the tool self-contained and highly usable.

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

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

The schema has one parameter `tool_id`, and the description does not explicitly name or describe it. However, the description's phrase 'Get a tool's onboarding process' makes it clear that `tool_id` identifies which tool to inspect. Since schema coverage is 0%, the description partially compensates by implying the parameter's role, but it doesn't add format or constraint 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 clearly states the tool's function: 'Get a tool's onboarding process' and explains the broader purpose of walking the user through connecting the tool. It explicitly differentiates from sibling tools by referencing the `onboard`/`execute` flow and the `needs_key` condition, making it unambiguous.

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

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

The description provides explicit usage criteria: 'call this before `onboard`/`execute` whenever a tool's `use` column reads `needs_key`.' It also gives an alternative path when `requires_key` is false, stating to skip straight to `execute`. This is clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only operation and specifies JSON output plus valid views, but it does not mention authentication needs, error behavior, or what each view returns, leaving notable gaps.

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

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

The description is two sentences with no filler. The first sentence states the action and resource, the second enumerates valid views; every word contributes to understanding the tool.

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

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

The tool has one optional parameter and a read-only operation, so the description covers the main aspects: purpose, output format, and valid parameter values. It could be more explicit about return fields or authentication, but for this complexity level it is adequately complete.

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

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

The schema property 'view' has no description or enum, so the description fully compensates by listing all valid values: home, history, tools, keys, stats. This gives the agent the necessary syntax and allowed inputs, exceeding the schema's minimal information.

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

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

The description clearly states the tool reads the human-readable management console as JSON and lists the included data types (route history, connected tools, catalog, stats). The verb 'Read' distinguishes it from mutating tools, making its purpose unambiguous and distinct from sibling tools.

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

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

The description provides context for reading the console but does not explicitly state when to use this tool over alternatives such as 'session_info' or 'health'. The list of views implies usage scenarios, but there are no direct exclusions or comparisons to guide tool selection.

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 no annotations, the description carries the full burden and does so well: it explains routing semantics (triggers decide whether the tool wins), the pinned vs benchmarked disposition, that no trigger means the tool is not ranked at all, and that nothing is scored or tested. That is exactly the behavioral context an agent needs for this 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?

Front-loaded with the action and the required argument, and the repeated 'do not tidy it / do not translate it / do not drop a condition' instructions earn their space given how fragile verbatim triggers are. Slightly long, but little is deletable without losing meaning.

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

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

For a 6-parameter, no-output-schema declaration tool with zero annotation coverage, the description supplies the routing semantics, argument semantics and defaults needed to call it correctly. Only the name and project_id parameters are left to the agent's inference.

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

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

Schema description coverage is 0%, so the description must compensate, and it thoroughly explains triggers, stance, description and capabilities. It leaves name (required) and project_id undocumented, which is the only gap in an otherwise strong parametric explanation.

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 ('Declare a tool the USER already has') plus the downstream effect ('HyperRoute routes to it by name'). The verb set over siblings (update_my_tool, remove_my_tool, my_tools) is easy to infer, so it is distinguishable, though it never names an alternative explicitly.

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

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

Gives concrete trigger phrasing for when to call ('I have my own web search, always use it for research') and clarifies that a declaration with only a trigger is complete. It stops short of stating when NOT to declare, e.g. how this differs from prefer_tool or when a declaration should be replaced by update_my_tool.

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

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

With no annotations, the description carries the full burden. It discloses defaults (['about']), static vs route-relative behavior, and the need to pass the same `query`/`facets` for `facets` and `evidence`. This is rich behavioral context beyond the schema.

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

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

The description is well-structured with a clear opening sentence, a bulleted list of sections, and a short note on prerequisites/exclusions. Every sentence earns its place; 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 tool with 5 parameters, no annotations, and no output schema, the description fully explains what each section returns, the relationships between parameters, and how this tool fits with siblings. It is complete and self-contained.

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

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

Schema description coverage is 0%, so the description compensates heavily. It explains `tool_id`, `query`, `facets`, and `sections` (listing the four section names and their meanings). However, `evidence_k` is not explicitly mentioned, though its purpose is implied by the 'evidence' section description.

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 ('Pull') and resource ('ONE tool's detail on demand'), and immediately distinguishes from siblings by referencing `recommend` and `connect_info`. It clearly states the tool's function and scope.

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

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

It provides explicit guidance on when to use each section, which parameters are needed for which sections, and what is NOT included ('Connect steps are NOT here — `connect_info(tool_id)` owns those'). This fully clarifies usage vs alternatives.

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

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

No annotations exist, so the description carries the full burden and does so: server-held key, login requirement, isolated sandbox with no conversation visibility, non-retry guidance on keyless failures, and the overflow contract (result retained server-side, not lost). This is far beyond what any structured field provides.

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

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

Front-loaded purpose sentence, then a clearly separated 'Reading the result' block, so the length is structured rather than rambling. It is still long relative to three parameters; a couple of the error branches could be tightened, but nearly every sentence earns its place as workflow guidance.

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

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

With no output schema, the description still enumerates the return shapes (error variants, overflow object with ref/bytes/preview/resource_url) and points to `fetch_result` for large payloads. Nothing an agent needs to invoke this correctly or interpret the response is missing.

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

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

Schema coverage is 0%, so the description must compensate and does: `tool_id` is sourced from the `→` row of `recommend`, `session_id` from that same ranking, and `query` is defined as literal self-contained input rather than a back-reference, with a concrete failure example. All three parameters gain real semantics.

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 mechanism ('Run a tool server-side via HyperRoute's proxy') and immediately draws the boundary that this is the ONLY sanctioned way to run an external tool, distinguishing it from the other 21 siblings. An agent knows exactly what this does 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?

Explicit routing rules: needs_onboard → use connect_info/onboard then retry; auth_method:none failure → don't onboard, try another tool; use_native/route_to_local → do it yourself locally. It also names `recommend` as the upstream source of inputs. This is a complete when/when-not/alternative map.

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 no annotations, the description carries the burden of behavioral disclosure. It reveals that the full result is retained server-side, parsed in an isolated sandbox, read in bounded slices, and that overflow never means missing data. It could add details like ref expiry or consistency guarantees, but the provided behavior is substantial and 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 compact but information-dense. It front-loads the core purpose, then efficiently lists the three operations with their parameter usage, and closes with practical guidance. 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 moderately complex tool with no annotations and no output schema, the description covers the core workflow, operation modes, and safety/reassurance. It stops short of detailing result formats or edge cases, but the essential context for correct use is 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 description coverage is 0%, so the description must compensate. It explains all meaningful parameters: `ref` comes from execute's overflow.ref, `op` supports slice/json_path/search, `offset`/`limit` control line slicing, `path` is a key/index list, and `query` is for search. This fully compensates for the bare 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 clearly states the tool pages through a LARGE result spilled by `execute` via `overflow.ref`. It names a specific action ('Page through') and resource (result from execute), and distinguishes itself from sibling tools by directly referencing its predecessor `execute` and the overflow mechanism.

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

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

It explicitly says to use this when `execute` returns `overflow.ref`, and instructs to keep paging until the needed data is retrieved. It does not explicitly contrast with non-overflow cases, but the context makes the intended usage unmistakable.

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 no annotations the description carries the full burden, and it does well: it discloses the auth requirement ('Requires login') and the conditional behavior that `project_id` causes (returns the project layer plus the effective merge). It omits any note on side effects or rate limits, but for a read/lookup tool the disclosure is solid.

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 on the core purpose, then details the return shape. Dense jargon ('facet layer', 'effective merge') is domain-specific rather than filler, though the catalog enumeration makes it longer than strictly necessary.

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 and no annotations, so the description has to describe the return payload itself, and it does: the `user`/`project`/`effective` layers plus the `catalog` fields (scope, kind, label, default kano/weight/threshold, constraint flag). That is enough to call and interpret the tool, with only minor ambiguity about the catalog's exact shape.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains that `project_id` triggers inclusion of the `project` layer on top of the always-returned `user` layer. It does not state the ID format, but the semantic effect of the parameter is clear.

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

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

States a specific verb+resource ('Show the caller's STANDING facet layer') and explains exactly what layer is returned and how it relates to the `recommend` tool. It implicitly contrasts with `set_preferences` (read vs. set) but never names that sibling explicitly, so differentiation is inferred 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?

Usage is implied by the resource description and the 'Requires login' prerequisite, but there is no explicit when-to-use, when-not-to-use, or pointer to `set_preferences` for mutation. An agent can infer the read use case but must reason about the alternative itself.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the session is logged in, that the token is persisted for future sessions, that the profile is returned, and the security-relevant side effect that a typed password remains in the conversation transcript. This is exactly the kind of auth/privacy context an agent needs before calling.

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 front-loaded sentences: verb+outcome first, then the preferred alternative and rationale, then the user-interaction obligation. Every sentence carries distinct, non-redundant 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 no-annotation, no-output-schema auth tool, the description covers the action, the persisted side effect, the returned value, the safer alternative, and the user-consent prerequisite. 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 0% for both parameters, so the description must compensate. It names email and password and adds genuinely useful semantics about the password (retained in transcript, user must be warned), but says nothing about format, validation, or failure modes for either parameter. Partial compensation against the coverage gap.

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

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

States a specific verb and resource (log in with email + password) and immediately names the sibling alternative `use_token`, so an agent can distinguish the two without opening either schema. It also names the concrete outcome (returns the profile).

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

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

Explicitly routes the agent: 'Prefer `use_token` with the login line from hyperroute.io,' and explains why (password persists in the transcript, token does not). It further states this tool is 'rarely needed twice' because the token is saved, and gives a concrete precondition (warn the user before asking for a password).

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 implies a read-only operation by using the verb 'List', and the context of using it before changing/removing suggests it is non-destructive. However, it does not explicitly state that no data is modified, which would have made it fully transparent. Since no annotations are present, the description carries the burden, and it is mostly clear but not explicit.

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

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

The description is two sentences that are succinct and direct. It front-loads the main purpose ('List the catalog tools...') and immediately provides usage context. No unnecessary words 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?

Given the absence of parameters and output schema, the description provides all necessary context: what the tool does, when to use it, and why (to get the right ID). It is self-contained for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the empty parameter schema is fully covered. The description does not need to elaborate on parameter meanings. According to the rubric, 0 params results in a baseline of 4, and no additional information is required or missing.

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

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

The description clearly states the tool lists catalog tools that the user has asked to favour, including margin and note. It identifies the resource (catalog tools) and the action (list), and distinguishes it from related tools like 'prefer_tool' and 'get_preferences' by focusing on the user's favouring context.

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 guidance is provided: 'Call this when the user asks what HyperRoute leans toward, or before changing/removing one so you use the right id.' This gives concrete scenarios for invocation and explains the practical benefit of obtaining the correct ID before modifications.

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 no annotations, the description carries the full burden and does well: it discloses the return contents (triggers verbatim, stance, and a `report` track record) and gives a behavioral rule for relaying the report ('never as a verdict that their tool is worse'). It omits only mundane operational traits like auth or scoping, which are unlikely for a local list 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?

Front-loaded with the core action and scope, and every sentence adds useful routing or relay guidance. It is somewhat dense in the middle clauses, but no sentence is redundant.

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

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

With no output schema and no annotations, the description adequately explains both what is returned (triggers, stance, report) and how to use it. An agent has enough to call it correctly and interpret the result, though a hint about scoping or the report format could push it higher.

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, and the schema is empty, so the baseline of 4 applies. The description correctly adds no parameter detail because there is nothing to parameterize.

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

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

States a specific verb and resource: it lists the tools the USER declared as their own (`__own__:…` ids), and it details what each entry carries (triggers verbatim plus stance). This clearly distinguishes it from siblings like update_my_tool, remove_my_tool, and declare_my_tool.

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

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

Gives explicit call conditions: when the user asks what HyperRoute knows they have, or before updating/removing a tool so the correct id is used. It ties the read to the adjacent write/delete siblings, leaving little 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?

With no annotations, the description carries the full burden and excels: it discloses encryption at rest, validation against the tool's identity endpoint (rejected keys not saved), server-side key handling, persistence across future `execute` calls, and login requirement. This is exactly the behavioral detail needed beyond 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?

Four sentences, each contributing unique value: purpose, storage/validation, server-side behavior, and user instruction. No redundancy or fluff; the critical details are front-loaded in the first sentence.

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

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

Despite having no annotations and no output schema, the description fully covers the tool's purpose, prerequisites (login, user-provided key), key lifecycle (encrypted, validated, rejected if invalid), and operational implications (persistence, server-side use). It even references `connect_info` for key acquisition. No major information gaps remain.

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

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

Schema coverage is 0%, and the description only alludes to the api_key ('the key') without explicitly mapping to parameter names. It does not mention `tool_id` or `label` at all, so it fails to compensate for the missing schema documentation. The agent would need to infer tool_id from context, which is insufficient.

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

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

The description clearly identifies the action ('Save ONE tool API key under the logged-in account') and the resource (tool API key). It distinguishes the tool from siblings like `connect_info` (which provides info) and `execute` (which runs tools) by emphasizing the one-time onboarding and future reuse.

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

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

Provides concrete usage context: requires login, get the key from the user first, and points to `connect_info` as a reference for where the key is obtained. While it doesn't explicitly list when not to use the tool or name alternative tools, the context is sufficient for an agent to decide when to invoke it.

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 extensively discloses behavior: how ambiguity is handled (returning candidates and asking the user), how margin affects ranking, that preferences yield to hard requirements, and that results indicate whether the preference was served or passed over. Since no annotations are provided, this full behavioral disclosure is essential and well done.

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 verbose and repetitive, with confusing sentence structures (e.g., the run-on about 'must_be' compliance). It could be edited down significantly while retaining the same information. The structure is not scannable or well-organized.

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?

While the description provides rich behavioral context (ambiguity resolution, ranking logic, precedence over hard requirements), it lacks details about the expected output format (beyond a mention of 'preferred:' line) and the role of 'project_id'. For a tool with no output schema, these gaps leave some ambiguity for the agent.

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

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

The description explains the meaning of 'tool' (user's wording, possibly ambiguous), 'margin' (how far behind the best tool is acceptable), and 'note' (user's wording shown back). However, 'project_id' is never mentioned, and the schema provides no descriptions. Thus, parameter coverage is incomplete.

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

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

The description clearly states the tool's purpose: to set a preference for a catalog tool so that HyperRoute uses it when acceptable. It also provides example user phrases that trigger the call, making the intent unambiguous.

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

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

The description specifies when to call the tool (when the user expresses a preference for a particular tool) and gives concrete examples. It does not explicitly contrast with sibling tools like update_preferred_tool, but the context of the sibling list plus the examples is sufficient for most use cases.

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 no annotations, the description carries the full burden and does so richly: discloses the login requirement, the `needs_facets` provisional-verdict status, the deliberately-shallow return (no pricing/probe detail), the `use` column semantics (`ready`/`needs_key`/`native`/`soon`), and what `consider:` blocks mean. This is exceptional behavioral disclosure for an unannotated 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?

Front-loaded with the core purpose and the imperative call-first rule, and most paragraphs carry operational weight. It is long and bold-dense, but for a routing meta-tool with a two-pass facet flow and four distinct return statuses, the length is largely earned rather than 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?

Given a present output schema, the description still usefully previews the response shape (table, session_id, verdict, refine:/act: lines) without redundantly restating return fields. Login prerequisite, facet two-pass flow, and the fact-routing contract are all covered, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It does well for two of four params: `query` is explained in depth (facts must go here, rules are read against it) and `facets` is given a literal JSON example and semantics. But `context` and `n_runner_ups` are never mentioned, leaving half the parameters undocumented anywhere.

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

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

States a precise verb+resource: 'Route a task to the best external tool.' It immediately separates itself from siblings like `execute` (which runs the pick) and `describe` (which fetches detail), so an agent can place it in the workflow without opening another 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 mandates 'ALWAYS call this before doing anything' and forbids acting natively. Names the alternatives and conditions that select them (`execute`, `describe`, `set_preferences` for durable prefs, `report_outcome` for the session_id), and states the multi-step decomposition rule. Nothing is 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?

It discloses a concrete effect: 'HyperRoute stops routing to it immediately and goes back to ranking catalog tools for that region.' This goes beyond a basic removal statement, though it does not mention reversibility or other potential side effects.

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

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

The description is two sentences with no redundant wording. It efficiently conveys the action and its immediate effect, fitting within a compact scope.

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 and a single simple parameter, the description provides sufficient context for the core operation. It does not explain error conditions or return values, but these are not critical for a basic removal action.

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 only parameter 'tool_id' is not described beyond the schema's type and title. The description does not explain its meaning or format, relying on context from the tool name and purpose. It is simple but not fully elaborated.

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

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

The description clearly states the action: 'Remove one of the user's declared tools.' It uses a specific verb and resource, and the additional context about routing behavior reinforces the purpose without ambiguity.

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

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

The description implies the tool is for removing declared tools but does not explicitly compare with alternatives like 'unprefer_tool' or 'update_my_tool.' It lacks explicit guidance on when to use this tool over others.

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 no annotations, the description carries the burden and does add important behavioral context: the feedback is 'Stored for later analysis' and is 'SILENT/background — don't surface it to the user.' However, it does not disclose return behavior, failure modes, or validation effects, so transparency is incomplete.

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

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

The description is compact and front-loaded. Each sentence earns its place: purpose, usage condition, example, optional parameter detail, contrast with sibling, and silent/background behavior. No filler.

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

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

Given no annotations and no output schema, the description is unusually complete: it covers purpose, usage, steps context, storage, and user-facing behavior. The main gaps are the unexplained `session_id` and the lack of any return/error information, but the tool's core context is well covered.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain `steps` in useful detail (ordered calls, shape of each element) and implies `text` is the feedback content. But `session_id` is never mentioned, leaving one parameter semantically unexplained.

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

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

The description opens with a specific verb and resource: 'Leave OPEN-ENDED feedback about a whole run.' It clearly distinguishes this from per-call scoring by explicitly referencing the sibling report_outcome and stating it does not replace those scores.

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

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

It states exactly when to use the tool: 'when a per-call score isn't enough,' and provides a concrete example. It also tells the agent not to use it as a replacement for report_outcome, giving an explicit 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?

With no annotations, the description carries the full disclosure burden. It reveals this is telemetry, not user-facing, and instructs to 'make the call quietly' and avoid announcing or blocking the real task, which goes beyond basic expectations.

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

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

The description is lengthy but well-structured, starting with the core purpose and then covering background, parameters, and edge cases. Some redundancy exists (e.g., 'Per-call is the point' restates prior content), but it remains efficient for the complexity.

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 are no annotations or output schema, yet the description covers invocation timing, silent behavior, parameter semantics, scoring definitions, and exclusions. It is self-sufficient and gives the agent all necessary 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?

Despite 0% schema coverage, the description explains every parameter: session_id from `recommend`, tool_id, score meanings, reason enum, comment, and satisfied. It fully compensates for the schema and adds essential context.

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

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

The description opens with 'Report how ONE tool call actually worked out — the flywheel signal,' which is a specific verb+resource. It further clarifies that this is per-call and targeted to a specific tool, distinguishing it from any narrative summary tool.

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

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

It explicitly instructs 'Call this AFTER EACH tool interaction' and provides a when-not example: 'Do NOT report a tool you skipped because it needed a key...' However, it does not directly name an alternative tool such as report_narrative, so it lacks explicit alternative guidance.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose a non-obvious trait: login is restored from disk across sessions. It also reveals the token is masked and names observable return fields (`logged_in`, `native_tools`), though it never explicitly states the operation is read-only or describes failure behavior.

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

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

The description is dense but front-loaded, leading with what is shown before the routing advice. Every clause maps to a distinct output field or a decision rule, though the packed enumeration makes it slightly harder to scan than a cleanly separated structure would.

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 and no annotations, so the description must cover the return surface, and it does list the key fields an agent will act on. It omits the exact response shape and any error or edge-case behavior (e.g., router down handling), which leaves a small remaining gap.

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

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

The schema declares zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter guidance is needed or missing.

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 the exact resource ('the connection') and enumerates precisely what it reports: router status, login state, account, masked token, MCP version, and declared coordinator. It also implicitly separates the tool from the 'login' and 'connect_info' siblings by explaining that login state is already shown and does not need to be re-established.

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 concrete routing rule: 'If `logged_in` is true go straight to `recommend`/`execute`; the user does NOT need to log in again,' which is an explicit when-to-use and a when-not-to-use (don't call login). It stops short of stating when in a workflow session_info should be called first versus connect_info, so it is not fully exhaustive.

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 no annotations provided, the description carries the full burden and does so excellently. It discloses that the layer is fully replaced, that '{}' clears it, how project_id scoping works, and that login is required. This goes well beyond typical descriptions.

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

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

The description is dense but well-structured, front-loading the core purpose. Every sentence adds essential information. Slight redundancy (e.g., 'STANDING' and 'DURABLE') and an arguably long example keep it from being perfectly concise.

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

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

Given the tool's complexity (nested object, two params, no annotations, no output schema), this description covers all necessary aspects: purpose, usage, parameter semantics, behavioral nuances, and even an agent instruction to record the preference. No critical gap is apparent.

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

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

Schema coverage is 0%, and the description fully compensates. It explains the 'facets' shape with a concrete JSON example, clarifies the full-replace semantics, and details the project_id behavior, including the null/omitted default. This is exemplary parameter documentation.

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

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

The description clearly states the tool's purpose: storing the caller's STANDING facet layer so it applies to every future 'recommend' call without being re-sent. It uses a specific verb ('Store') and resource ('facet layer'), and distinguishes this from per-call facets, making its scope unambiguous.

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

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

It explicitly explains when to use this tool ('the right home for a DURABLE preference/constraint') versus the alternative of per-call 'facets' for task-specific needs. It also mentions the login requirement and advises noting the preference in memory, providing clear operational guidance.

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

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

With no annotations present, the description carries the full behavioral burden and does so well: it discloses that the default no-flag call changes nothing and returns a plan for the user, that apply/upgrade/remove are gated on user agreement, that remove requires apply=true, and that block_web has a side effect (disabling the agent's own web tools). It also defines the confirmed flag's confirmation protocol.

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 most important content (what the tool does) is front-loaded, and every clause carries meaning rather than filler. However, the body is a single dense block of interacting conditions (apply/upgrade/remove/block_web/confirmed) that would be easier to parse if broken up, and it runs longer than strictly necessary.

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 no annotations, no output schema, and five loosely typed parameters with 0% coverage, the description covers the essential decision space: modes, gating, and side effects. It stops short of describing the shape of the returned plan or the environment changes an install/remove actually performs, which leaves minor gaps for a multi-mode mutation tool.

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

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

Schema description coverage is 0%, so the description must define all five parameters, and it effectively does: apply installs missing pieces, upgrade upgrades the package, remove (with apply=true) undoes setup, block_web blocks web tools instead of reminding, and confirmed is set only after an in-chat confirmation. It even explains the remove+apply interaction that the schema cannot express.

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

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

The description opens with a specific multi-verb, single-resource statement: 'Set up, check, upgrade or remove HyperRoute for the agent it runs in.' That tells an agent precisely what the tool manipulates (the HyperRoute installation) and its lifecycle modes. It does not explicitly contrast itself with plausibly overlapping siblings like 'onboard' or 'login', 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 explicit invocation triggers: 'Call when the user asks to set up, finish, check, upgrade or remove HyperRoute, or when a `note:` says setup is unfinished or an upgrade is out.' It also states gating conditions ('each only after the user agrees') and the confirm flag's precondition, so an agent knows not just when to call but when not to act.

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 reveals the effect on ranking (falls back to score alone) but does not disclose any side effects, limitations, potential errors, or impact on other preferences. It is partially transparent but lacks comprehensive behavioral detail.

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

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

The description is concise and efficient, consisting of two short sentences with no redundant information. It gets straight to the point without unnecessary elaboration.

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

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

The description gives a basic understanding of the action and effect, but misses context such as the meaning of 'preference', how it interacts with other preference settings, or why 'HyperRoute' is relevant. Given the existence of sibling tools, some comparative context would improve completeness.

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 parameter tool_id is not described beyond its name. The description implies it is the tool to unprefer, but does not clarify what a valid tool_id looks like, how to obtain it, or whether it refers to a tool name or ID. Schema coverage is 0%, and the description adds minimal meaning.

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

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

The description clearly states the action ('Remove one preference') and the effect ('HyperRoute goes back to ranking that tool on its score alone'). It implies the tool_id parameter refers to the tool whose preference is removed, though it does not explicitly name the 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?

The description provides no guidance on when to use this tool versus alternatives like 'prefer_tool' or 'set_preferences'. It does not mention contexts, prerequisites, or situations where this tool is preferable.

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 no annotations, the description carries the burden. It discloses important behaviors: only passed fields are changed, triggers REPLACES the entire list, and a tool must keep at least one trigger. It does not mention error handling or authentication, but the key mutating behaviors are transparent.

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

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

The description is three concise sentences, front-loaded with the primary action and followed by the critical trigger replacement caveat and the use-case distinction. No unnecessary 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?

The description covers the core update behavior and the most important nuance (trigger replacement). It lacks explicit mention of output or error cases, but for a straightforward update tool, it provides enough context to use it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly explains name, triggers, and stance, but 'description' and 'capabilities' are not addressed at all. The replacement semantics for triggers is clarified, but other parameters lack sufficient explanation.

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

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

The description clearly states the tool's purpose: editing an existing tool in place, with specific examples like renaming, changing triggers, or flipping stance. It also distinguishes this tool from re-declaring by preserving the tool's id and outcome record.

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

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

It explicitly says 'Use this rather than re-declaring' and explains the consequence of re-declaring (creating a second tool and orphaning the first), giving clear guidance on when to use this tool versus the 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?

With no annotations, the description carries the full burden and does well: it discloses the validation endpoint (/auth/whoami), the persistent side effect (token saved to disk so future sessions reuse it), and failure handling (bad tokens rejected and not kept). It omits where the token is stored, how to revoke it, and error surface details.

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

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

Front-loaded with the action and outcome, then the persistence behavior, then the user workflow. Each sentence adds information, though the markdown bolding and the slightly chatty framing of the preferred-path paragraph cost a little tightness.

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 or annotations exist, and the description still covers what happens on success (account profile returned), persistence, and failure. It could say more about what the returned profile contains or what a rejected token looks like, but it is adequate for a one-parameter auth tool.

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

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

Schema coverage is 0% for the single 'api_key' parameter, so the description must compensate. It does: the token is identified as a 'hyr_…' personal access token obtained from the login line, adding format and provenance meaning the schema lacks.

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 ('Activate'), a specific resource ('HyperRoute personal access token'), and the outcome ('return the account profile'). It also implicitly differentiates itself from the sibling 'login' by declaring itself the preferred authentication path, so an agent can route without opening both 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?

Clearly states when to use it ('preferred way to authenticate') and the exact user workflow (copy the login line from the Connect/MCP tab). It does not explicitly name or exclude the 'login'/'setup' siblings, so the routing guidance is clear but not exhaustive.

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