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 provided, the description carries the full transparency burden. It discloses that a trigger-only declaration is complete, that stance defaults to pinned, that no trigger means no ranking effect, and that the tool is never scored or tested. This is highly transparent about behavior and limitations.

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 into focused paragraphs for triggers, optional fields, stance, and limitations. It is somewhat repetitive in places but remains readable and front-loads the most important usage 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?

The description provides sufficient context for an agent to use the tool correctly: when to call it, how to format triggers, what optional fields mean, how stance affects routing, and what the tool does not do. No output schema is needed for this action, and the absence is not a 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 0%, but the description compensates for most parameters: triggers are explained in depth, description and capabilities are clearly defined, and stance is elaborated. However, project_id is not mentioned and name is only implicit, leaving minor gaps.

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

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

The description clearly states a specific action ('Declare a tool the USER already has') and its purpose (so HyperRoute routes to it by name when the user said to). It distinguishes this tool from siblings by focusing on user-declared tools and trigger-based routing.

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

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

The description gives explicit call conditions with examples ('Call this when the user says...'), explains the trigger format, and clarifies stance behavior including the default 'pinned'. It does not explicitly contrast with sibling tools like update_my_tool or prefer_tool, but the usage context is clear enough.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It fully discloses key behaviors: server-held key, returns only the result, requires login, isolated sandbox, query must be literal, and detailed error/overflow handling. It even explains that overflow is retained server-side and not lost.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then clarifies query semantics, then systematically presents error handling in bullets. The structure is logical and scannable, with no redundant or filler content.

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

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

Given the complexity of this tool (auth, sandboxing, error codes, overflow, multiple fallback paths), the description is completely adequate. It explains return value shapes, error strategies, and references to sibling tools (connect_info, onboard, fetch_result). No output schema exists, so it compensates fully.

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 thoroughly: tool_id is explained as coming from the '→' row of 'recommend', and query is defined as the LITERAL, self-contained input, with a concrete counterexample to prevent misuse. This adds substantial meaning beyond 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 explicitly states the tool's function: 'Run a tool server-side via HyperRoute's proxy.' It uses a specific verb ('run') and resource ('tool server-side'), and clearly distinguishes this from alternatives by declaring it 'the ONLY sanctioned way to run an external 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?

Provides explicit guidance on when to use this tool versus alternatives: it's the only sanctioned way to run an external tool, and error handling tells the agent when to try another tool, perform the task natively (use_native), or onboard the user. This is clear the 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?

With no annotations, the description carries the full burden. It discloses that the data is fetched once (caching behavior), requires no login, and details the exact structure of each entry (scope, kind, label/description, bundle default, constraint). This goes well beyond a generic 'list facets' statement.

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, front-loaded with the core purpose ('full list of facets'), followed by a dense but efficient description of entry fields. No filler; every clause contributes value.

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

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

Despite lacking an output schema, the description comprehensively explains what each entry contains and how it should be used. It also covers auth ('No login required') and cache semantics ('fetched ONCE'), making it complete for a zero-param tool.

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

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

The tool has zero parameters and an empty schema, so the baseline is 4. The description correctly focuses on the output structure instead of parameters, which is appropriate for a no-argument catalog tool.

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

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

The description clearly states the tool retrieves 'the full list of facets HyperRoute ranks tools on,' serving as a reference for filling `facets` on `recommend` and `set_preferences`. This distinguishes it from siblings by framing it as a static catalog rather than an action-oriented 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 says 'fetched ONCE — reference for filling facets on recommend and for choosing what to persist with set_preferences,' giving clear use cases. It doesn't state when not to use it, but the context is strong. The 'No login required' note adds practical usage guidance.

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

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

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?

No annotations are provided, so the description must carry the burden. It discloses that the tool sends an email and does not complete the reset itself, which is useful. However, it omits details such as rate limits, error behavior for invalid emails, or session invalidation.

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, front-loaded with the core action, and every sentence adds value. No 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 one-parameter tool with no output schema and no annotations, the description covers the action, the follow-up steps, and the fact that the actual reset is handled on the website. It lacks some edge-case details but is adequate for simple use.

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 a single 'email' parameter with 0% description coverage. The description's phrase 'by email' clarifies the parameter's role. But it adds no format or validation details, and the parameter's meaning is largely self-evident from its name.

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 'Request' and resource 'password-reset code by email', and clarifies the follow-up steps, distinguishing it from sibling auth tools like login and use_token.

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 this tool only requests the reset code, and instructs to complete reset on website then log in with new password or use_token, giving clear context for when to use this vs subsequent login steps. It doesn't explicitly state when not to use, but the flow implies 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?

With no annotations, the description carries the full burden. It discloses that login is required, explains the merge behavior into recommend, and clarifies the layered return (user, project, effective). This provides meaningful behavioral context, though it does not describe error handling or performance characteristics.

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, front-loaded with the core purpose, and every sentence adds value: it explains the standing layer, the return layers, and the login requirement. Nothing is wasted.

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 main aspects of the tool: what it returns, the optional parameter, and the auth requirement. No output schema exists, so the lack of return structure details is a minor gap, but the description is adequate for a simple getter.

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 0% description coverage, but the description explains the project_id parameter by stating that the project layer is returned when project_id is given. This adds meaning beyond the bare schema field.

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 shows the caller's standing facet layer, a specific resource, and uses the verb 'Show'. It distinguishes from siblings like set_preferences (write) and facets_catalog (list available facets) by explaining the merge behavior into recommend.

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 clear context for when to use this tool: to view the standing facet layer. It explains the different returned layers and the optional project_id. However, it does not explicitly mention alternatives or when not to use it, so it lacks exclusions.

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 are provided, so the description carries the burden. It discloses the auth requirement ('No auth required') and specifies the return contents (interface + artifact version, tool/facet counts). The word 'Check' implies a read-only operation, adding behavioral transparency despite not explicitly stating side effects are absent.

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 concise sentence that front-loads the action ('Check') and provides essential details without waste. Every phrase adds value.

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

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

For a tool with no parameters and no output schema, the description adequately conveys the purpose, return values, and auth requirement. It is complete for its simplicity and 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and none are present in the schema.

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

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

The description clearly states the tool checks router status and retrieves model bundle details (interface + artifact version, tool/facet counts). It is specific and distinguishes itself from sibling tools by focusing on system health rather than user or data operations.

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

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

The description implies when to use it: to verify the router is up and inspect the loaded model. It notes that no auth is required, which is useful context. However, it does not explicitly mention alternatives or exclusions, though for a health check this is not a significant gap.

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. It discloses that keys are masked, only metadata and last-test status are returned, and that login is required. This adds meaningful behavioral detail beyond the tool's name.

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 that quickly deliver purpose, behavior, and prerequisite. There is no wasted text; every phrase serves a distinct function.

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, no-output-schema tool, the description is mostly complete. It specifies the scope, the masking behavior, and the prerequisite. However, it does not explicitly state the return format (e.g., array, object), though 'metadata and last-test status surface' gives a strong hint.

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 description does not need to explain parameter semantics. According to the rubric, a baseline of 4 is appropriate for zero-parameter tools.

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

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

The description uses a specific verb ('List'), identifies the resource ('tool credentials'), and adds scope ('under the logged-in user'). It also distinguishes itself by noting keys are masked, which is unique among the sibling tools. This is a clear, specific purpose statement.

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

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

The description gives a clear usage context: it is for the logged-in user and requires register/login first. It does not explicitly name alternatives or exclusion cases, but the context is strong enough 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?

No annotations are provided, so the description fully carries the transparency burden. It discloses that the token is saved for future sessions, that a fresh verification code is emailed, and that the password remains in the conversation transcript. This is rich behavioral context beyond the basic login action.

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. The first sentence states the action and key effects; the second provides crucial usage guidance. No unnecessary words or repetition; every sentence earns its place.

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

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

Given the absence of an output schema and annotations, the description covers the main behavior, side effects, and guidance. It could be slightly more complete by mentioning error cases (e.g., invalid credentials) or the structure of the returned profile, but it sufficiently addresses the tool's purpose and context.

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

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

The schema only lists 'email' and 'password' with no descriptions (0% coverage). The description adds the important caveat about password retention in the transcript, which gives semantic weight to the password parameter. However, it does not specify formats, validation rules, or other per-parameter constraints, so coverage remains partial.

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 that the tool logs in with email and password, logs the session in, and returns the profile. It also distinguishes itself from the sibling tool 'use_token' by noting that this method saves the token and is rarely needed twice.

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?

Excellent usage guidance: explicitly recommends using 'use_token' instead whenever possible, with a clear rationale (password retained in transcript vs. token not). Also mentions the unverified account flow and directs to 'verify'.

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 are provided, so the description carries the full burden. It discloses that an email is sent, that the code is one-time, and that no password is needed. This gives the agent a clear behavioral model. It doesn't mention rate limits or code expiration, but for a simple initiation tool this is adequate.

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 efficient, using two short sentences to convey purpose and follow-up action. It is well-structured with the key behavior front-loaded and no extraneous 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 tool with one parameter and no output schema, the description covers the essential flow: it emails the code and points to the next verification step. It could mention code expiration or whether the user must already exist, but given the tool's simplicity, 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?

The schema has only one parameter (`email`) with 0% description coverage. The description adds meaning by clarifying that the email is the recipient of the magic link, which is not fully explicit in the schema. This compensates for the lack of schema-level 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 clearly states the tool's function: email a one-time login code/magic link to the given email address. It distinguishes itself from siblings like `verify_login` and `login` by specifying the initiation step of a passwordless login 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?

It provides clear usage context by describing the passwordless login flow and explicitly instructing the next step (call `verify_login` with the code). However, it doesn't explicitly mention when to use this over alternative auth tools like `login` or `use_token` beyond the passwordless 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?

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?

The description transparently discloses that the data is user-reported, not measured by HyperRoute, and that the tool should not claim the user's tool is worse. It also mentions the related update action, providing clear behavioral 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 well-structured with the core purpose first, followed by usage context and important caveats. It is slightly verbose due to repeated emphasis on 'user's own reports', but remains clear and focused.

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 fully covers what the tool does, when to use it, the nature of the data, and the follow-up action (update_my_tool). It provides sufficient context for an agent to decide when and how 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 input schema has zero parameters, and the description does not need to explain any. The schema is fully covered, and there is no missing parameter information to add.

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 that the tool reports the user's own track record on declared tools, per capability region, including alternatives. It also distinguishes this from HyperRoute measurements, making its purpose 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 explicitly states when to deliver the report: when the user asks how their tools are doing, or when a declared tool repeatedly underdelivers. It also provides actionable guidance on what to relay and what to avoid.

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 stating 'List', but does not explicitly state that no side effects occur. Given the absence of annotations, the description carries the full burden; however, the action is self-evidently non-destructive, so this is adequately 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 concise, containing two sentences that front-load the purpose and provide usage context. Every sentence adds value without redundancy.

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

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

The description explains what the tool returns (tools with triggers and stance) and when to call it, which is sufficient for a low-complexity tool with no parameters. It does not detail the exact output schema, but that is not required given the simplicity.

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

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

The tool has no parameters, and the schema is empty, so the baseline of 4 applies. No additional parameter explanation is needed.

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

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

The description clearly specifies the tool lists user-declared tools with their triggers and stance, and distinguishes it from sibling tools like 'my_tool_report' by focusing on the user's own declarations. The phrase 'List the tools the USER has declared as their own' is a specific verb-resource combination.

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 given: 'Call this when the user asks what HyperRoute knows they have, or before updating/removing one so you use the right id.' This clearly states when to use the tool and provides a rationale for retrieving IDs 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 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 provided, the description carries the full burden and excels: it discloses the output format (table, session_id, verdict, refine, act), the meaning of each `use` value, the shallow nature, the role of `situation` in rule evaluation, the two-pass facet flow, and anonymity. It also notes when the tool routes back to the agent ('native'), which is a critical behavioral nuance.

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 long and dense, but it is organized into topical paragraphs (purpose, situation, facets, flow) and every sentence carries actionable information. While it could be more succinct with bullet points, the complexity of the tool justifies the length and the structure is logical, front-loading the core directive.

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 is exceptionally complete given the tool's complexity. It covers the calling convention, parameter usage, response format, edge cases (needs_key, native), and integration with sibling tools. The output schema is present, but the description still explains the response semantics in detail. The only minor omission is `n_runner_ups`, which does not detract from overall 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?

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `context` and `facets` with examples, and `query` is implicit from the tool's purpose. However, `n_runner_ups` is not mentioned at all, leaving a gap for that parameter. This is a minor omission given the depth provided for the other parameters.

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

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

The description clearly states 'Route a task to the best external tool' and emphasizes it is the mandatory first step, distinguishing it from sibling tools like describe, execute, and set_preferences. The verb 'route' and resource 'external tool' are specific, and the role as central router 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?

The description explicitly says 'ALWAYS call this before doing anything' and provides detailed routing instructions, including when to use set_preferences for durable preferences and describe for additional details. It explains the flow for each `use` column value, leaving no ambiguity about when this tool applies versus 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?

With no annotations, the description fully discloses key behaviors: creates an UNVERIFIED account, emails a one-time code, does NOT log in, and requires verification to get an API key. It also explains the one-time nature and credential reuse, providing rich behavioral context beyond the bare 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?

The description is three well-structured sentences, front-loading the core purpose and then adding critical behavioral details. Every sentence adds value with no redundancy or 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?

The description effectively captures the registration flow, including the unverified state, email verification, and API key acquisition. It lacks an explicit statement of the tool's return value, but given the absence of an output schema, the behavioral outcome (code emailed) is sufficiently conveyed.

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 explains the role of `email` and `password` as registration credentials, but completely omits the optional `display_name` parameter. This incomplete coverage leaves an agent without insight into an available input, though the schema's title/default provide some inference.

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 with a specific verb ('Register') and resource ('a new HyperRoute account'), and distinguishes it from the sibling `verify` and `login` tools by explicitly noting it does NOT log in yet and requires a follow-up verification step.

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

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

The description gives clear usage context: this is the one-time registration step, and explicitly instructs to call `verify` next. It also indicates the login is saved for future sessions, implying registered users should not re-register. However, it doesn't explicitly name `login` as the alternative for existing users.

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 fully bears the transparency burden. It discloses behavior such as login restored from disk, the token being masked, how native_tools is used for comparison, the consequence of an empty baseline, and an environment variable fix—far beyond a simple output 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?

The description is two well-structured paragraphs: first establishes purpose and immediate usage, second adds a critical operational caveat. Every sentence contributes useful 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 zero-parameter utility with no output schema, the description is remarkably complete. It covers what is reported, when to invoke it, how to interpret login state, and how to remediate a missing native_tools baseline, giving the agent everything needed to act.

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 description does not need to explain parameter syntax. It does describe the returned fields and interpretation, which adds value over the empty schema and meets the baseline for parameterless tools.

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 specifies the tool's function: showing the MCP session's connection state and enumerating exact fields (base URL, login status, account email/user_id, masked token, coordinator). 'Call this first' establishes its unique role among sibling tools, distinguishing it from health, whoami, and connect_info.

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 explicit usage timing: 'Call this first — if logged_in is true you can go straight to recommend/execute.' It also tells when the user does NOT need to log in again, and includes troubleshooting advice for empty native_tools, making usage conditions and next steps 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?

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, the description carries full weight. It openly states the tool has no routing effect, is optional, and is only for report wording. This is highly transparent about its non-behavior and purpose.

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

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

Front-loaded with purpose, but includes some redundancy (e.g., repeats the 'decides nothing' idea) and a slightly wordy style. Still reasonably tight and structured.

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?

Provides thorough context: purpose, relation to sibling tools, when to use, and caveats. No output schema exists, so description does not need to explain return values, but its advisory role is fully specified.

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 description must compensate. It implicitly explains 'description' as the text to map, but does not mention the 'name' parameter (optional with default). Some context is provided, but not full parameter coverage.

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

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

States a specific action (preview), resource (named capabilities), and clarifies it is optional and decides nothing. Clearly differentiates from declare_my_tool by explaining what it is NOT for.

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 instructs not to call before declaring and explains that poor matches should not prevent declaration. Names the alternative routing tool (declare_my_tool) and clarifies the advisory nature.

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 provided, the description must carry the burden of explaining side effects, permissions, or error handling. It only mentions that 'only the fields you pass are changed', which describes the partial-update behavior but does not address potential failure modes or consequences of omitting fields. The behavioral transparency 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?

The description is concise, consisting of two sentences, and front-loads the primary action immediately. It avoids unnecessary verbiage and each sentence contributes directly to understanding the tool's purpose and usage.

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 three parameters and a partial-update behavior, but the description does not explain parameter meanings or provide any context about expected outcomes, errors, or permissions. While the purpose and a use case are given, an agent would lack the information needed to invoke it correctly without additional domain knowledge.

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 0% description coverage, and the description fails to explain the meaning of 'margin' or 'note'. It only refers to them as fields to change, leaving their semantics ambiguous. The description does not compensate for the missing schema descriptions, so an agent would not understand what values to supply.

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 ('change one preference's margin or note') and specifies the resource (preference) and the fields involved. It also provides a usage condition ('when the user says the bias should be stronger or weaker'), which helps distinguish it from other preference-related tools.

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

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

The description explicitly tells when to use the tool: 'Use this when the user says the bias should be stronger or weaker'. It also adds a nuanced clarification ('actually, only use it when it's nearly as good') that narrows the scenario. However, it does not explicitly mention when not to use it or name alternative tools, so it falls just 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?

With no annotations, the description carries the full burden and does well: it discloses validation via /auth/whoami, saving to disk, automatic reuse in future sessions, and rejection of bad tokens. It also mentions the security benefit (password not exposed). It does not cover potential side effects of disk storage (e.g., security implications or storage location), but the core behavior is 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 concise and well-structured: the first sentence states the core action, the second explains the mechanism (validation and persistence), and the third provides context on why this method is preferred. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's action (saving a token to disk), the description covers what it does, what it returns (account profile), how validation occurs, persistence behavior, failure handling, and security rationale. No output schema exists, but the return is clearly stated. It could mention error responses or storage details, but overall it is sufficiently complete for an AI agent to select and invoke 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 coverage is 0% and the only parameter is 'api_key' with no description. The tool description compensates by explaining that this is a personal access token with the 'hyr_…' prefix, clarifying the expected value format and purpose. This adds meaning beyond the raw schema, though it doesn't explicitly map 'api_key' to the token phrase.

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: 'Activate an existing HyperRoute personal access token (hyr_…) and return the account profile.' It uses a specific verb ('Activate') and resource, and distinguishes itself from authentication siblings like login (password-based) and whoami (profile query) by focusing on token-based activation and persistence.

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

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

The description explicitly positions this as 'the preferred way to authenticate' and explains why (user mints token on website, password never enters conversation), giving strong contextual guidance. However, it does not name alternative tools explicitly or state when not to use this tool, only implying the distinction from other auth methods.

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, so description carries full burden. It discloses that on success the account is verified, session is logged in, and the token is saved to disk for all future sessions – a critical side effect. It also warns that recovery codes are shown once and should be saved.

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 the action, then important side effects and warnings. 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?

The description covers the main purpose, when to use, side effects, and response contents (api_key, recovery_codes). With no output schema, explaining the response is valuable. For a simple 2-param tool, this is 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 has 2 params (email, code) with 0% description coverage, so description must compensate. It indirectly describes them: 'email verification code' implies the code parameter, and the email used at registration is implied. It doesn't provide format details, but for simple string params this is sufficient.

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 'Confirm the email verification code from `register`' – a specific verb, resource (the verification code), and source (register). This clearly differentiates from sibling `verify_login`.

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 ties the tool to the `register` flow, implying this is the step after registration. It doesn't explicitly name alternatives, but the context is clear enough for the agent to know when to use it vs `verify_login`. No exclusions stated.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses the key side effects: 'logs the session in' and 'saves the token for future sessions.' It does not cover edge cases like code expiry or error behavior, but the main behavioral traits are clearly stated.

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, well-structured sentence that front-loads the primary action and then states the side effects. Every phrase adds value, with no redundancy or filler.

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

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

For a simple two-parameter login tool, the description is largely complete: it names the input context, the mechanism, and the outcome. It does not specify return values, but no output schema is provided and the side effects may be the primary concern. A small gap is the lack of explicit guidance about matching the email to the one used in `login_link`.

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 partially compensates. It explains that the code is the one emailed by `login_link`, giving context for the `code` parameter, but it does not clarify that `email` must match the address used in `login_link` or describe any format constraints.

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

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

The description uses a specific verb ('Complete') and identifies the exact resource ('passwordless login') and mechanism ('code emailed by login_link'). It clearly distinguishes this from sibling tools like `login` or `verify` by referencing the emailed code 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?

The phrase 'code emailed by login_link' clearly implies the prerequisite step and situates this tool as the follow-up to `login_link`. It does not explicitly list exclusions or alternatives, but the intended usage context is unambiguous enough.

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 disclosing behavior. The verb 'Return' implies a read-only operation, but this is not explicitly stated. The description mentions the session prerequisite but does not address error cases, side effects, or authentication requirements beyond the implied logged-in state.

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 that states the action and resource, then lists the fields. There is no filler, redundancy, or unnecessary detail.

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, and the description covers all necessary aspects: it specifies the resource, scope, and the output fields. Since there is no output schema, the explicit field list compensates. Minor details like error conditions are absent, but not critical for this simple tool.

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

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

The tool takes no parameters, so the empty schema needs no explanation. The description's field list pertains to output, not input, and the baseline for zero-parameter tools is 4, which is appropriate here.

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

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

The description uses the specific verb 'Return' and identifies the resource as the account profile, explicitly listing the fields (id, email, display_name, tier, status, verified). It clearly scopes to the account currently logged in to the session, making it distinct from sibling tools like session_info.

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 'currently logged in to this session' provides clear context for when to use the tool, indicating it targets the current user. However, it does not explicitly mention alternative tools or exclusions, so it falls short of a full 5.

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