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

No annotations are supplied, so the description must carry behavioral disclosure. It lists the response fields (requires_key, connected, signup URL, steps, field) and gives a safe user-facing workflow, but it never explicitly states that the operation is read-only or side-effect-free. That is useful context, but for an unannotated tool it leaves key behavioral guarantees implicit.

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

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

Two short sentences with no filler; the field list is compressed and the not-connected workflow is stated directly. The first sentence is terse enough to be slightly cryptic, but it is not padded or repetitive.

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

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

For a one-parameter, no-output-schema tool, the description gives the returned field names and the next-step workflow, which is enough to attempt a call. It still leaves the parameter meaning and the exact return semantics (types/format of `steps` and `field`) unclear, so it is adequate rather than complete.

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

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

The single parameter `tool_id` has 0% schema description coverage and is not explained in the description. 'A tool's...' weakly implies the ID identifies a tool, but no format, source, or example is given. With low schema coverage the description should compensate, and it does not.

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

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

The description names the resource ('A tool's connect steps') and enumerates returned fields, so the agent can infer it retrieves connection status/instructions for a tool. However, it uses a noun phrase rather than a clear verb and never explicitly says 'returns' or 'gets', leaving the action implicit. It mentions `onboard` as a related sibling but does not sharply differentiate this tool from all alternatives.

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

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

It gives a concrete branch: when not connected, show the steps, ask for the key, then call `onboard`. That names a condition and the next tool, which is stronger than generic guidance. It does not state what to do when already connected or when to call this versus other info tools, so it stops short of full when/when-not coverage.

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, yet it says nothing about permissions/auth requirements, whether the data is live or cached, or what distinguishes the views behaviorally. 'The user's console' implies per-user scoping, which is the only real behavioral signal.

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

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

Two tight fragments, front-loaded with the resource and return type, with zero filler. The terseness is efficient but edges toward under-specification rather than being padded.

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

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

There is no output schema and no annotations, so the description is the only source of information about a tool that returns view-dependent JSON. It never describes what any view yields, so an agent cannot predict the response shape before calling.

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 schema declares 'view' as an unconstrained string with no enum, so the description's enumeration 'home | history | tools | keys | stats' is genuinely necessary information the schema lacks. However, it doesn't explain what each view returns, leaving the agent to guess the meaning of 'keys' or 'stats'.

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?

Names the resource ('the user's console') and the return format ('as JSON'), which distinguishes it from siblings like session_info or my_tools. The verb is only implied (read/fetch), but the scope is unambiguous enough for selection.

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 lists view values but never says when to use this tool versus session_info, my_tools, ranking, or describe — several siblings that plausibly overlap in returning user/session data. No exclusions or routing guidance is given.

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 that the tool is unseen in ranking unless a trigger fires, is "never scored," and that stance governs whether a catalog tool can displace it. Undisclosed: duplicate-name behavior and what project_id scoping does.

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?

Dense but front-loaded — routing behavior first, then parameter rules, then the stance default. Every clause carries information; only the nested quotation styling makes it slightly harder to parse on a first read.

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

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

For a 6-parameter, no-annotation, no-output-schema tool, the description covers what an agent needs to call it correctly: required triggers, their content rules, stance semantics, and routing consequences. The one real hole is project_id pairing with the session/onboard siblings.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: triggers get explicit content rules (verbatim, every condition kept, user's language), stance gets both enum values explained, and description/capabilities are labeled "report wording only." project_id is entirely undocumented in both schema and 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?

States a specific verb and resource ("Declare a tool the user already has") and grounds it with a concrete user-utterance example. The routing explanation ("routes to it when a trigger fires; otherwise it is not in the ranking") makes the effect distinguishable, though no sibling such as prefer_tool or update_my_tool is named for contrast.

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

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

Gives a recognizable situation for use ("use my Xero thing for invoices") and an explicit procedural rule: "No trigger given: ask for it." It also explains the default stance and when benchmarked applies. It stops short of saying when to choose update_my_tool or prefer_tool instead.

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?

Since no annotations are provided, the description is highly valuable for setting behavioral context. It defines the precise content of the various sections (e.g., 'price' is cost, 'facets' are per-facet scores) and specifies dependencies between inputs like `query` and `facets`.

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 definition is information-dense, but the structure is slightly disjointed, mixing output structure details with input parameter requirements and a connection hint at the end. It is concise but not exceptionally 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?

It is quite complete for a retrieval tool, as it provides a comprehensive breakdown of what the returned data will look like for various request types (e.g., providing `query` for `facets`). The dependency mapping is a strong point.

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

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

With 0% schema description coverage, the description is essential. It explicitly defines the available values and semantic meaning for the `sections` array (e.g., 'about', 'price', 'facets') and explains critical input dependencies that are not captured by 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 tool is described as providing 'One tool's detail,' which is clear about the action but lacks specific verbs that distinguish it from other data retrieval tasks. It lists the types of data retrieved (sections) rather than stating the high-level operational purpose.

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

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

Usage guidance is extremely weak. It only notes that `sections` defaults to `['about']`. It does not advise when to use this tool versus other tools like `fetch_result` or `get_preferences`.

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 disclose the key behavioral trait: overflow is not data loss, so the agent should page. It does not state whether the response signals remaining/truncated state, what happens on an expired ref, or any size limits, leaving meaningful behavioral 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?

Three compact sentences, front-loaded with purpose before the op reference and the pagination caveat. The op enumeration is telegraphic but dense rather than padded; nothing is redundant.

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

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

For a 6-parameter tool with zero schema descriptions and no output schema, the description covers how to call it but not what comes back — no indication of how paging progress is signaled or how to know you have everything. Adequate to invoke correctly, incomplete for confident iteration.

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 this is strong compensation: `op` modes are enumerated and each is bound to its parameter (`offset, limit lines`, `path=[key|index…]`, `query`), and `ref` is explained by its origin in a reply. It still omits whether limit/offset are line-based for json_path and search, and any default/maximum values.

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

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

States a specific verb and resource ('Read a large result kept server-side') and even shows the in-band handle format `fetch_result('<ref>')` that triggers it. No sibling tool in the list reads a server-side overflow buffer, so the agent can distinguish it immediately.

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 trigger condition is explicit — a reply containing a ref — and the three modes are mapped to their purposes (slice for lines, json_path for key/index traversal, search for query matching). It does not state any exclusions or failure cases (e.g., invalid/expired ref), so it falls 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 behavioral burden. It discloses returned layers (user, project, effective), catalog defaults, and a constraint marker, which adds useful read-return context, but it does not explicitly state read-only behavior or explain scoping/auth implications.

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

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

It is a single dense sentence with little waste, but it is not front-loaded with the tool's purpose. The jargon-heavy structure makes the definition harder to parse than needed.

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

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

There is no output schema and the only parameter is undocumented, so the description needs to do more. It hints at return categories but leaves the project_id behavior and exact preference structure unclear.

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% and the only parameter, project_id, is never explained in the description. The mention of a 'project' layer hints at project scope, but it does not clarify whether project_id is optional or what it filters.

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 never states a clear verb or plainly says it retrieves preferences. It describes an internal 'facet layer' and catalog structure, so the tool's actual purpose is only inferable from the name and sibling 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?

There is no guidance on when to call get_preferences versus set_preferences or other siblings. It implies a read of standing preferences but does not specify context, prerequisites, or 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?

With no annotations, the description carries the full burden and does disclose two non-obvious traits: credentials are persisted for future sessions, and the agent will see the plaintext password (with an instruction to warn the user first). It omits failure behavior and where/how the credential is stored, which keeps it short of full disclosure.

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

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

Three short clauses, front-loaded with the action, then the persistence note, then the alternative-auth routing. Every sentence carries distinct information 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 two-required-param auth tool with no annotations and no output schema, the definition covers purpose, side effect (session persistence), the preferred sibling, and the user-consent step. What's missing is post-login behavior and error/expiry handling, which an agent would otherwise have to discover by calling 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%, so the description must compensate, but it only restates the two property names (email, password) with no format, validation, or handling notes. The parameter names are largely self-documenting, so this is adequate but adds little beyond the schema.

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

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

The description states a specific verb and resource ("Log in with email + password") and immediately scopes it against the sibling alternative ("Prefer `use_token`"). An agent can distinguish this from `use_token` or `session_info` without opening any schema.

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

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

It explicitly names the preferred alternative (`use_token`), which is real routing guidance. It doesn't state when email/password login is actually required (e.g. no token available, first-time setup), so the condition that selects this tool is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden, yet it never states whether this is a read-only listing, what 'margin' and 'note' mean, or in what order results come back. The only clue that it is a read operation is the possessive framing, which is inference rather than disclosure.

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

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

It is a single short sentence with no padding, which is good, but the trailing 'with margin and note' is cryptic enough that the brevity reads as under-specification rather than efficiency.

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

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

There is no output schema and no annotations, so the description is the only place a caller could learn what a 'preferred tool' record looks like or what 'margin' and 'note' contain. For a zero-parameter read tool that is cheap to call, that gap is tolerable but still a real omission.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The phrase 'with margin and note' refers to returned fields rather than inputs and is too vague to count as added value.

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 phrase 'the catalog tools the user favours' does suggest a listing of preferred tools, but it is a noun phrase rather than a verb+resource statement, and 'with margin and note' is opaque. It does not differentiate itself from close siblings like my_tools, get_preferences, or ranking, so an agent cannot confidently tell what this returns versus those.

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

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

There is no when-to-use guidance at all: no conditions, no exclusions, and no mention of prefer_tool/unprefer_tool as the way preferences get populated. The agent is left to infer from the name alone.

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

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

No annotations are provided, so the description carries the full burden. It usefully clarifies that the returned outcome record belongs to the user and should be relayed as theirs rather than as a verdict on the tool, but it does not state whether the operation is read-only, whether it has side effects, or what access constraints apply.

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

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

The description is short and front-loads the resource, but the phrasing around `report`: their own outcome record is syntactically awkward and forces the agent to parse what is being returned. It is appropriately sized but not cleanly 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?

With no output schema, the description must explain the return shape, and it only partially does so by naming triggers, stance, and report. It does not fully clarify the record structure or how this tool relates to sibling tools that also deal with the user's tool preferences and declarations.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4.

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

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

The description identifies a specific resource—the user's declared own tools—and adds that it exposes triggers, stance, and an outcome record. However, it never uses a clear verb such as list, retrieve, or describe, and it does not distinguish this tool from close siblings like my_preferred_tools or declare_my_tool.

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

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

It gives an instruction about how to relay the returned record, but no guidance on when to call this tool, when not to call it, or which sibling to use instead. With many related tools available, that guidance is absent.

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 real work: it discloses that the key is tested, encrypted, never leaves the server, and persisted for later runs. Gaps remain on what happens if the test fails, whether an existing key for the same tool is overwritten, and whether anything is returned.

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

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

Two short sentences, front-loaded with the action and value proposition, with the prerequisite as a closing directive. No filler; the parenthetical security clause earns its place.

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

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

For a credential-writing tool with no annotations and no output schema, the description covers security and persistence but omits failure behavior, idempotency/overwrite semantics, and what the caller should expect on success. Adequate but leaves real gaps.

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

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

Schema coverage is 0%, so the description must compensate. It gives meaning to api_key (must be supplied by the user, tested and encrypted) and to tool_id implicitly via 'for one tool', but the label parameter is never mentioned, and no format examples for tool_id are given.

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 concrete verb and resource: save the user's API key for one tool, with the scoping detail that it is per-tool. It never contrasts itself with adjacent siblings such as login, use_token, or setup, so an agent must infer which credential path applies.

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 prerequisite 'Get the key from the user first' is useful, and 'reused on every later run' implies this is a one-time setup step. But there is no explicit statement of when to choose this over login/use_token/setup, nor what to do if a key already exists.

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

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

With no annotations the description carries the full burden, and it discloses genuinely non-obvious behavior: ambiguity returns `candidates` rather than guessing, the margin scale and its tuning direction, and that a failed must-have still excludes the tool. It omits what a successful call returns or whether an existing preference is replaced, and says nothing about project scoping.

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?

Dense and front-loaded: the serving semantics come first, then parameter notes in a compact order. The telegraphic 'note: their wording' phrasing is slightly cryptic, but no sentence is 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?

There is no output schema and no annotations, so the description is the only source of behavioral detail; it covers the core effect and margin tuning well but leaves `project_id` entirely unexplained and never states the success-side outcome or precedence over existing preferences. Adequate for the main path, incomplete at the edges.

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

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

Schema coverage is 0%, so the description must compensate, and it does for three of four parameters: `tool` (user's wording, ambiguity handling), `margin` (default 0.10, 0–1 scale, wider/narrower interpretations) and `note`. `project_id` is never mentioned in either schema or description, which caps the score.

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

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

States a specific verb and object ('Favour a catalog tool') plus the exact effect: the tool is served whenever acceptable and within `margin` of the best. It does not explicitly name the siblings it is not (unprefer_tool, my_preferred_tools), so it stops short of a 5, but the verb alone makes the contrast obvious.

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

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

Gives a concrete trigger phrase ('I like Kagi, use it when it's acceptable') and an explicit branch for the ambiguous case: return `candidates`, ask the user, never pick. No explicit when-not guidance or named alternatives such as unprefer_tool for removal, so it is clear context rather than full routing.

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

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

With no annotations, the description carries the burden alone; it discloses what the response contains (top 10 plus rationale and confidence) and that evidence=true expands to probes behind the top 5. It says nothing about read-only nature, cost, or whether the extra evidence is expensive, leaving meaningful 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?

Two compact sentences, front-loaded with the return contents and then the optional flag. No filler, though the phrasing is telegraphic enough that some clarity is traded for brevity.

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 annotations, no output schema, and 0% schema coverage, the description must compensate for a lot. It handles the evidence flag and response shape adequately but leaves the two required parameters and any safety/cost profile unexplained.

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 all three parameters depend on the description. It explains evidence (adds probes behind the top 5 scores) well, but run and item are undocumented — an agent must guess the run identifier format and what an 'item' index means.

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 resource ('the full ranking behind one run item') and enumerates the returned substance (top 10, placement rationale, confidence), so an agent can tell it retrieves ranking detail for a single run item. It does not name a sibling it differs from, so it falls short of the top score.

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

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

The description gives no when-to-use guidance and never mentions alternatives like run, fetch_result, or describe. The only usage information is the evidence flag's effect, not when to call this tool versus another.

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 at all, the description carries the full burden; it does disclose the key effect that routing to the tool stops immediately. However, it says nothing about irreversibility, whether the declaration can be recovered by re-declaring, permissions/ownership requirements, or whether callers using the tool are notified.

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

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

Two short clauses with the action and its consequence front-loaded and zero filler. 'now' is slightly vague about timing but does not bloat the text.

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

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

A destructive, single-parameter tool with no annotations and no output schema needs the description to cover reversibility, identifier format, and post-removal state. None of these are present, so the definition is not sufficient to call it safely.

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% and the single parameter 'tool_id' is undocumented. The description does not clarify whether the value is an opaque identifier or the declared name returned by my_tools/declare_my_tool, which is the main likely source of a failed invocation.

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

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

States a specific verb (remove) and resource (a declared tool), and adds the operational consequence that routing to it stops. The phrase 'declared tool' links it to the declare_my_tool/my_tools family, though it never explicitly contrasts with unprefer_tool, which is the nearest ambiguous sibling.

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

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

No when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as unprefer_tool (stop preferring) versus remove_my_tool (delete the declaration). The agent must infer the distinction from the tool names alone.

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

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

With no annotations, the description carries full behavioral burden, but it leaves key traits unexplained. "Silent" is ambiguous, and it does not clarify whether feedback is stored, who sees it, whether authentication is required, or what side effects occur.

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 very compact and front-loads the usage condition before explaining the steps structure. It is slightly cryptic at the start, but every sentence carries information and there is no filler.

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

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

For a tool with no annotations, no output schema, and 0% schema description coverage across three parameters, the definition is incomplete. It omits the required text parameter's meaning, top-level session_id semantics, and behavioral details about what reporting does.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully expands the nested steps structure with fields like session_id, tool_id, query, verdict, and thinking, but it does not explain the required top-level text parameter or the top-level session_id.

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 indicates it reports "whole-task feedback" when per-run scores are inadequate, which gives some sense of the tool's role. However, the core action is vaguely called "Silent whole-task feedback" rather than explicitly saying it submits narrative feedback, and it does not distinguish itself from the sibling report_outcome.

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

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

It gives a clear triggering condition: use this when per-run scores miss the point, with an example ("never checked the primary source"). It does not mention alternatives or exclusions, such as when report_outcome would be more appropriate.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: the call must be invisible to the user, and a useless/blocked score reopens the item, after which the `reopened` field holds the next tool's result or the handed-back item. That reopen loop is exactly the kind of consequence an agent could not infer. It stops short of describing what the call itself returns.

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?

Purpose and the silent constraint are front-loaded, and every subsequent line carries information. The telegraphic 'item: ... / score: ...' style is dense but a little fragmented, requiring the reader to reassemble the rules.

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

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

For a five-parameter, no-annotation, no-output-schema tool, the description covers all parameters, the reopen consequence, and the invisibility requirement. The only gap is the return shape beyond the mention of a `reopened` field.

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% and the schema declares no enums, so the description must supply all meaning — and it does: it defines the item format, enumerates all five score values with parenthetical semantics for useless and blocked, enumerates the six reason values and the condition ('below full') under which they apply, and explains comment and satisfied. This is near-complete compensation for an empty schema.

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

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

States a specific verb and resource: 'Score one tool run.' The item parameter clarification ('<run>/<n>' from a run reply) pins down what a run is. It doesn't explicitly differentiate from the sibling report_narrative, which is the only thing keeping it from a 5.

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

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

Provides one strong usage constraint ('Silent: never mention it to the user') and a negative rule ('Never report a tool skipped for a missing key'), but never states plainly when to call it (e.g. after every tool run) or how it relates to the sibling report_narrative. Usage is implied rather than spelled out.

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

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

No annotations exist, so the description carries the full burden, and it does disclose a lot: per-item independent ranking, the outcome branches (best tool runs / 'do it yourself' / connect a key), that 'ask' mode runs nothing, and the critical constraint that queries are literal and the tool cannot see the chat. Remaining gaps are failure semantics across a batch, async/pagination behavior, and what happens if an owed report is not supplied.

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 critical directive leads the description and each subsequent line covers a distinct concern (item shape, reports, mode), so it is front-loaded and largely waste-free. It loses a point for telegraphic fragments like 'reports: owed scores' and '<run>/<n>' that trade clarity for brevity without a reader already versed in the system.

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

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

This is a complex routing tool with no output schema, no annotations, and 0% schema coverage, so the description must carry everything — and it omits the shape of what comes back, how a run id is obtained for the reports format, and how it composes with sibling tools like fetch_result and report_outcome. Adequate to invoke correctly in the common case, but not complete for a tool of this complexity.

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

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

Schema description coverage is 0% and the schema exposes items as an untyped array, so the description must do the work — and it largely does, defining item forms ('strings, or {query, facets?, tool?}'), the literal/self-contained nature of query, the purpose of tool, the score enum for reports (full|partial|useless|blocked), and mode's default and values. Gaps remain: 'facets?' is never explained, 'owed scores' is undefined, and the '<run>/<n>' reference format is never introduced.

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

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

The description states a specific role: this is the single entry point for all outside lookups (search, page, third-party API), and explains the mechanism — each item is ranked, the best tool runs, and its result returns. That is a clear, non-tautological statement of what the tool does, well beyond the bare name 'run'. It does not, however, differentiate itself from siblings such as ranking, describe, or fetch_result, which sit in the same lifecycle.

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?

Strong operational guidance: 'never do one yourself first', 'One item per lookup; batch all known lookups in one call', the auto-vs-ask mode split ('nothing runs; the user picks from the top 3'), and explicit when-not behavior ('needs a key = stop and ask the user, never do it another way'). What is missing is routing against sibling tools — it never tells the agent when to use run versus fetch_result or report_outcome.

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

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

No annotations exist, so the description carries the full burden. It does add genuinely useful behavioral detail beyond a bare name: the token is masked (a security-relevant fact) and the login state is authoritative enough to skip re-authentication. However, it never states that the call is read-only/side-effect free, nor how fresh or cached the status is.

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 dense sentence plus a short conditional note — well front-loaded and free of filler. Slight deduction because 'Router status' and 'declared coordinator (`native_tools`)' are compressed to the point of near-opacity for a reader without prior context.

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

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

With no output schema and no annotations, the description must effectively serve as the return-value contract, and it does by listing the fields returned. What remains unexplained is the semantics of the values (what 'router status' states exist, what a 'declared coordinator' means in practice), which an agent may need to interpret results.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description appropriately spends no space on inputs.

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

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

The description enumerates exactly what the tool surfaces: router status, login state and account, masked token, MCP version, and declared coordinator. That gives an agent a concrete picture of the resource being inspected, and the trailing note about logged_in=true hints at its relationship to the `login` sibling. It never states a verb ('returns'/'inspect'), so the purpose is inferred from the field list rather than declared.

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

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

The only usage signal is implicit: 'logged_in=true: no need to log in again' suggests checking this before calling `login`. There is no explicit statement of when to call it (e.g., at session start), no mention of alternatives like `connect_info` or `get_preferences`, and no 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?

With no annotations, the description carries the burden and does well by disclosing that the tool replaces the whole layer and that {} clears it. It does not mention permissions, validation, or return behavior, which keeps it from a 5.

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

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

The description is compact and front-loaded, with the core behavior and replacement semantics stated immediately. The example earns its place by clarifying the facets shape without wasting space.

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 mutation tool with no annotations, no output schema, and a nested object parameter, the description covers the essential behavior and both parameters. It stops short of describing return values or error conditions, which 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?

Schema description coverage is 0%, so the description must compensate. It explains project_id's layer precedence and provides an example structure for facets, though the arbitrary nested facets object remains only partially specified.

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

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

The description uses a specific verb and resource: 'Store standing facets applied to every route,' and clarifies scope with examples. It distinguishes this from per-task facets, though it does not explicitly name sibling tools like get_preferences or prefer_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?

Usage is implied by the scope ('standing facets applied to every route') and the exclusion of per-task facets, which go on the item instead. However, it does not explicitly name alternatives or say when to use this versus get_preferences or prefer_tool.

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

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

With no annotations, the description carries the burden and does well: it discloses that the default is a dry-run that changes nothing, that mutations require explicit user consent, and that block_web=false switches the guard to reminder-only mode. It does not state whether install/remove are reversible, what side effects they have on the filesystem, or what a failed run looks like.

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

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

It is dense and front-loaded, and every clause carries information, but the telegraphic fragment style ('remove=true + apply=true undoes; each only on the user's yes') makes some conditions slower to parse than a bulleted mode list would.

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

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

Five optional booleans, no output schema and no annotations – the description covers modes, default behavior, and consent gating, which is most of what an agent needs. It leaves the return shape of the 'plan' and the reversibility of install/remove unstated, which matters for a tool that mutates an installation.

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

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

Schema coverage is 0%, so the description must compensate, and it does: all five booleans get functional meaning (apply installs, upgrade upgrades, remove needs apply, block_web=false degrades to a reminder, confirmed requires a prior yes from the user). It also conveys the interaction between remove and apply, which the schema cannot express. Type/default details remain schema-only, which is fine.

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 concrete verbs and a named resource: set up, check, upgrade or remove HyperRoute. That is far more specific than the bare name 'setup'. It doesn't name a sibling (e.g. onboard) that an agent might confuse it with, which keeps it out of the top band.

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

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

It states the default mode explicitly (no flags = report and return a plan, change nothing, show it to the user) and gives the selecting condition for each mode: apply=true installs, upgrade=true upgrades, remove=true+apply=true undoes. It also gates every mutation behind 'only on the user's yes' and defines the confirmed=true precondition, which is exactly when-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 and says nothing about whether the removal is idempotent, what happens if the tool was never preferred, or whether the change is persisted or per-session. 'Remove' implies mutation but no consequences are disclosed.

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

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

One short, front-loaded sentence with no filler, but the brevity crosses into under-specification rather than economy.

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?

A mutation tool with no annotations, no output schema, and 0% parameter coverage would need the description to explain prerequisites, error behavior, and identifier semantics. Almost none of that 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% and the single required parameter 'tool_id' is undocumented in both schema and description. The description adds no meaning about what identifier form is expected or whether it refers to a declared tool, so the coverage gap is not compensated.

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

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

The verb+resource pair ('Remove a preference') is clear enough to distinguish it from siblings like prefer_tool and set_preferences, but 'preference' is left ambiguous — it never says the preference is over a tool, which is only inferable from the tool_id parameter name.

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

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

No guidance on when to call this versus prefer_tool, set_preferences, or remove_my_tool, all of which exist as siblings and plausibly overlap. The agent must guess the boundary.

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 well: it discloses partial-update semantics ('only passed fields change'), the destructive replace behavior of triggers, and that the id and outcome record survive the edit. It stops short of stating error behavior for an unknown tool_id or name collisions.

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

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

Front-loaded with the action and the key semantic rule, then the triggers warning, then the identity guarantee. Dense but every clause carries information; the parenthetical field list is a small redundancy with the schema.

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

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

No output schema and no annotations, so the description must stand alone. It covers mutation semantics and replace-vs-merge well but is incomplete for a six-parameter tool where two parameters go unexplained and no return/permission context is given.

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 critical triggers-replacement rule and the null/omit-means-unchanged pattern, but two of six parameters (description, capabilities) are never mentioned, leaving the agent to infer they behave like the others.

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

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

States a specific verb and resource ('Edit a declared tool') and enumerates the editable fields (name, triggers, stance). The phrase 'Edit, don't re-declare' implicitly distinguishes it from declare_my_tool, though no sibling is named explicitly.

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

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

'Edit, don't re-declare: keeps the id and its outcome record' gives a clear condition for choosing this over re-declaring the tool. It doesn't address remove_my_tool or failure cases, but the primary alternative is covered.

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

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

With no annotations, the description carries the full burden, and it discloses the important traits: the token is validated before use, then persisted for future sessions, and the credential avoids exposing a password in chat. It leaves out failure behavior (what happens on an invalid token) and any expiry/revocation semantics.

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

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

Three short sentences, front-loaded with the action and credential, followed by the side effect and the sibling comparison. Nothing is padded or repeated from structured fields.

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 authentication tool with no annotations and no output schema, it covers what the agent needs: what to supply, where to get it, what happens to it, and why to prefer it over `login`. Only failure and expiry behavior are unaddressed.

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 single `api_key` parameter has no description, so the description must compensate. It does so by giving the expected prefix format and the exact UI path to generate the token, which is enough to populate the field correctly, though it does not say whether whitespace/prefix stripping is handled.

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

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

States a specific verb (log in) and the exact credential type expected (personal access token prefixed hyr_…), which separates it from the sibling `login` tool that uses a password. An agent can pick between the two without opening either schema.

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

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

Explicitly names the alternative (`login`) and states this one is preferred, with the reason (no password in the chat). It also tells the agent where to obtain the token. It stops short of stating when-not conditions, e.g. when no token exists yet, so it is not a full routing rule.

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