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

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

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

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

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

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

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

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

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

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

The schema has one parameter `tool_id`, and the description does not explicitly name or describe it. However, the description's phrase 'Get a tool's onboarding process' makes it clear that `tool_id` identifies which tool to inspect. Since schema coverage is 0%, the description partially compensates by implying the parameter's role, but it doesn't add format or constraint details beyond the schema.

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

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

The description clearly states the tool's function: 'Get a tool's onboarding process' and explains the broader purpose of walking the user through connecting the tool. It explicitly differentiates from sibling tools by referencing the `onboard`/`execute` flow and the `needs_key` condition, making it unambiguous.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden. 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, the description carries full burden. It discloses 'newest first' ordering, 'No login required', and the default behavior of omitting stream to get all three. While it doesn't mention output format or pagination, it gives meaningful behavioral context beyond a bare 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, followed by precise usage details and an alternative pointer. Every sentence serves a purpose with no padding.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usable values, ordering, and alternative. It omits any hint of the return shape, which would be useful, but the tool's simplicity and the description's clarity make it sufficient for most invocation decisions.

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 compensates by fully explaining the `stream` parameter with its enum-like values and default. The `limit` parameter is left to the schema, but its name and default are self-explanatory. Overall, the description adds significant meaning to the most ambiguous parameter.

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

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

The description opens with 'Browse HyperFeed', a specific verb and resource, and immediately clarifies the content: 'curated stream of agentic-AI news, agent releases/updates, and SF events.' It distinguishes from sibling hyperfeed_digest by explicitly pointing to it for personalized briefs, making the tool's unique role clear.

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

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

Usage is well-guided: 'stream ∈ {news, releases, events} (omit for all three)' and 'For a user's personalized morning brief use hyperfeed_digest instead' provide explicit when-to-use and an alternative. 'No login required' sets context for when authentication is unnecessary.

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 transparency burden and does a good job disclosing behavioral details: personalization logic, ranking criteria, and the existence of a 'last-delivered watermark' that defaults when since is not provided. However, it doesn't explain whether the watermark is updated automatically after delivery or describe response format, which leaves minor ambiguity.

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 sentences, each earning its place: the first defines what it is, the second tells when to call, the third explains parameters and follow-up. It is front-loaded and concise 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 one-parameter tool with no output schema, the description is fairly complete: it explains what the tool returns (news/releases/events), the usage protocol, and the related hyperfeed_react action. It doesn't detail the exact output structure, but the 'brief' wording implies a deliverable text, which is sufficient for an agent 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 schema only provides the parameter name and type, but the description adds crucial meaning: since is an ISO-time filter, and if omitted, the last-delivered watermark is used. This fully covers the single parameter, compensating for the 0% schema description coverage.

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

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

The description clearly states the tool's purpose: it delivers the user's personalized daily brief of high-relevance news/releases/events, ranked by recency, engagement, and interests. The verb 'call' and resource 'daily brief' are explicit, and it's distinct from siblings like hyperfeed_subscribe and hyperfeed_react.

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

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

The description gives explicit when-to-use guidance: 'Call this each morning and deliver it.' It also explains parameter usage (pass since for new items, otherwise use watermark) and directs the agent to report engagement via hyperfeed_react, which is a clear reference to the follow-up action.

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 transparency burden. It explains that positive actions influence future recommendations and dismiss hides the item, and also tells the agent not to narrate the call. While it doesn't disclose return values or error cases, the behavioral side effects are well outlined.

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 sentences, front-loaded with the purpose, then action semantics, then a usage instruction. Every sentence adds value and there is no repetition or fluff.

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 two-parameter tool with no output schema and no annotations, the description covers purpose, action values, behavioral effects, and invocation timing. It could mention return values or idempotency, but the essential information for correct usage 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?

The description enumerates the valid action values, adding meaning beyond the bare schema (which has no descriptions). However, item_id is not explicitly explained, though its purpose is implied by the tool's focus on feed items. The schema coverage is 0%, so partial compensation only.

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 records user interactions with feed items, lists the supported actions, and positions it as the relevance loop. This distinguishes it from siblings like recommend or report_outcome, which have different purposes.

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 when-to-use guidance ('after the user engages') and how to invoke it ('silently'), and references report_outcome as a similar operation. It doesn't explicitly state when not to use it, but the context is clear enough for correct 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 burden of behavioral disclosure. It does mention that re-calling is safe ('safe to call again to refine') and describes the semantics of fields (e.g., `interests` as standing topic hints). However, it does not disclose what the tool returns, whether it overwrites previous settings, or if any side effects (like triggering a digest) occur. This is moderately transparent but lacks critical operational details.

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

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

The description is concise and well-structured, using a single paragraph that front-loads the purpose, then lists each parameter with backtick formatting. Every sentence adds value—there is no filler or repetition. The density is appropriate for five parameters and zero schema coverage.

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

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

For a 5-parameter tool with no schema coverage, no annotations, and no output schema, the description covers purpose, parameter semantics, and usage timing comprehensively. It even includes practical advice like using chat history for `interests`. However, it omits the return value or error behavior, which would be useful for the agent to confirm success, leaving a slight gap in 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 description fully compensates for the 0% schema description coverage by explaining every parameter: `streams` ⊆ {news, releases, events} with default all, `interests` as standing topic hints, `owner` as {name,email,timezone}, `operator` as {agent,framework}, and `cadence` as 'daily'. This provides semantic meaning beyond the bare schema types (which are generic arrays/objects/null) and includes usage nuance like including chat history in `interests`.

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: 'Set up (or update) the user's HyperFeed subscription so the digest is scoped and personalized.' This uses a specific verb (set up/update) and resource (HyperFeed subscription), and it distinguishes from siblings like hyperfeed_digest (which likely retrieves the digest) by focusing on the subscription setup.

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 direct usage guidance: 'Call once at first run; safe to call again to refine.' It also explains the cadence context ('cadence is daily (you pull each morning)') and clarifies the purpose of parameters like `interests` and `owner`, which helps the agent know when and how to invoke it. It does not explicitly name alternative tools for exclusion, but the 'first run' and 'refine' signals make the appropriate timing 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. 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?

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?

With no annotations provided, the description carries the full burden and excels. It discloses that the tool is deliberately shallow, returns a compact table with `session_id`, `verdict`, `refine:` and `act:`, may return a provisional ranking (`status: needs_facets`), routes tasks back to the agent (`native`), does not split tasks, works anonymously, and reflects vault state when logged in. This is far beyond 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 long but structured and information-dense. It front-loads the core instruction, then covers output format, action mapping, and facets in logical blocks. While every sentence adds value, some details (e.g., exact JSON facet example) could arguably be in a separate reference, but the complexity of the tool justifies the length. No fluff.

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 a sparse schema, the description covers the tool's purpose, output schema essentials, required follow-up actions, the two-pass facet mechanism, alternatives, and edge cases (needs_key, soon, native). It is complete enough for an agent to invoke the tool correctly and handle its return payload, even without seeing the output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `facets` with a concrete example and the two-pass flow, and `query` is implied as the task to route. However, `context` and `n_runner_ups` remain undefined beyond their titles; `n_runner_ups` is somewhat self-explanatory but `context` is vague. Partial compensation, so not a 4, but clearly above baseline due to the facet detail.

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: 'Route a task to the best external tool.' It immediately separates this from siblings by stating it is the mandatory first step, with HyperRoute choosing the tool and executing via `execute`. The routing role is unambiguous and distinct from tools like `describe`, `execute`, or `set_preferences`.

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

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

The description is exceptionally clear about when to use this tool ('ALWAYS call this before doing anything'), how to interpret the `use` column (ready/needs_key/native/soon), and when NOT to use it via alternatives: `set_preferences` for durable preferences, `describe` for deeper details, and `report_outcome` for the session_id. It even covers the two-pass refine flow and decomposition expectations.

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?

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 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.