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

With no annotations to rely on, the description carries the full burden and does so admirably. It discloses that secrets are stored in macOS Keychain, never enter the assistant context via MCP elicitation, sessions auto-refresh, and force re-collects/overwrites existing secrets. These are meaningful behavioral traits beyond the bare action of 'authenticate'.

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 four compact sentences, each adding distinct value: core purpose, inference behavior, secret-handling guarantee, and force semantics. It is front-loaded and free of 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 all essential call-time knowledge: what secrets are, where they are stored, how inference works, context safety, auto-refresh, and when to use force. An agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds a concrete example for force ('rotated or expired keys') but mostly repeats the schema's own description, so it does not significantly extend parameter understanding.

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 action ('Authenticate a server') and adds concrete resource details: collecting and storing required secrets in macOS Keychain, with a distinct mechanism (MCP elicitation) and a force flag for re-collection. This clearly differentiates it from siblings like auth_status, search, and call_tool, which serve 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?

The description gives clear operational context: when to use force=true, how it handles missing auth schemas, and the fact that sessions refresh automatically. It does not explicitly name alternatives or state when not to use this tool, but the intended context is evident and actionable.

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

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

With no annotations provided, the description must carry the behavioral burden. It states output values but does not explicitly say the tool has no side effects or that it does not trigger authentication. The word 'Show' implies read-only, and the three statuses are useful, but 'partial' is undefined and no side-effect guarantee is 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, front-loaded sentence without filler. It states the verb, resource, scope, and output format in 18 words, making it easy for an agent to parse quickly.

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 low-complexity tool with one optional parameter, the description covers purpose, scope, and return values. Minor gaps remain—such as what 'partial' means and whether the tool modifies state—but these are not critical for an agent to invoke it correctly.

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

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

Schema coverage is 100% because the only parameter, 'server', has a description ('If set, return status for this server only. Otherwise all servers.'). The tool description merely mirrors that behavior without adding new meaning, so a baseline of 3 is appropriate.

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

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

The description uses a clear verb ('Show') and a specific resource ('authentication status') with an explicit scope ('one or all servers'). It even enumerates the return states (authenticated, partial, unauthenticated), which fully differentiates it from siblings like authenticate (which modifies auth state) and list_servers (which lists servers).

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 clearly implies when to use the tool: whenever an agent needs to inspect which servers are already authenticated versus those that are not. It does not explicitly contrast with authenticate, but the verb 'Show' and the return-state list make the use case obvious.

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

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

Annotations are minimal (just readOnly and destructive hints), but the description adds behavioral context: the server is spawned on first call, and the tool must exist (implying failure if not). It doesn't disclose other behaviors like authentication requirements or side effects, but the annotations likely provide basic safety info. The description adds value but not exhaustive detail.

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

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

The description is two sentences, concise and front-loaded with the primary action. The second sentence provides important usage guidance without wasting words. It's efficient but could be slightly more structured with explicit 'when to use' formatting.

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 that it's a dynamic call tool with a nested object parameter, the description is decently complete. It mentions the need to discover tools, but does not describe return values or error handling. However, the lack of an output schema means it could do more, but the combination of schema and description is sufficient for an agent to proceed.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds little beyond that, such as the implication of the 'server' parameter being a server reference, but it doesn't add significant meaning beyond the schema. Hence, baseline 3 is appropriate.

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

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

The description clearly states the tool calls a tool on a specific server, which is more specific than a generic 'call tool'. It also mentions the need for the tool to exist on the server, but doesn't explicitly differentiate from siblings like get_server_tools. Overall, it provides a clear verb and resource.

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 usage guidance: use get_server_tools to discover tools before calling. It also implies that the server is spawned on first call, which is an important context. This is strong guidance for when to use this tool versus alternatives.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals an important behavior: lazy connection to the server if not already connected. It also adds a token-cost hint (~100 tokens), which goes beyond the schema. It does not detail auth requirements or error behavior, but the read-only nature of 'Get' is apparent.

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

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

Two sentences with no filler, front-loaded with the core purpose and key behavioral note. The second sentence earns its place by giving strategic invocation guidance.

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

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

Given the simple 3-parameter schema and no output schema, the description is largely complete: it covers purpose, lazy-connect behavior, and the optimal calling strategy. It could mention that server names likely come from list_servers or clarify auth prerequisites, but these are minor gaps for such a focused discovery tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining summary_only's purpose ('cheap discovery') and the workflow of fetching full schemas for specific tools. This adds real semantic value over the structured parameter descriptions.

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

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

The description states a specific verb and resource: 'Get tools from a specific server.' It is clearly distinct from siblings like list_servers, call_tool, and search, so an agent can identify this as the tool-discovery operation without opening the schema.

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

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

The description gives actionable usage guidance: use summary_only=true for cheap discovery, then fetch full schemas for specific tools. It does not explicitly contrast this tool with siblings, but the intended workflow is clear and appropriately scoped.

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 only states the function and does not mention whether the operation is read-only, requires authentication, returns paginated data, or has any side effects. For a tool that lists configuration, the agent is left without explicit safety or state-change context.

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

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

Two sentences with no filler. The primary action is stated first, and the optional filter is added in the second sentence. Every word earns its place.

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

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

For a simple list tool with one optional parameter, the description covers the core function but lacks context about return value shape (no output schema exists), whether authentication is needed, or whether this is a safe read-only operation. Given the absence of annotations, a complete description should at least hint at these aspects.

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

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

Schema coverage is 100% (filter is fully described as 'Optional substring to filter on name, description, or tags.'). The description essentially restates the parameter without adding extra semantics like default behavior, match case-sensitivity, or wildcard support. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description uses a specific verb ('List') and resource ('configured MCP servers'), and clarifies the fields returned (descriptions and tags). It clearly distinguishes this tool from siblings like 'search' or 'recommend_servers' by framing it as an enumeration of configured servers, not a search or recommendation.

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 usage for listing servers and optionally filtering, but it does not explicitly state when to choose this tool over siblings (e.g., 'use search for semantic queries' or 'use get_server_tools to inspect a specific server'). There is no exclusion or conditional guidance, leaving some inference to the agent.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the sampling mechanism, the fallback behavior when sampling is unsupported, and the return structure (recommendations with scores and rationale). This provides good insight into how the tool behaves and its limits.

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

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

Three sentences, each earning its place: the first defines the action, the second defines the output and fallback, the third gives usage 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 read-only recommendation tool with no output schema, the description covers the input, mechanism, output, fallback, and usage context. It doesn't detail error conditions or the shape of the fallback catalog, but these are minor given the tool's simplicity.

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

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

The schema already documents both parameters (task_description and max_results) with clear descriptions, so the description adds no extra parameter context. It restates that the input is a natural-language task description without adding syntax or format details, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('recommend'), a resource (servers), and the input (a natural-language task description). It explains the mechanism (host LLM sampling) and output (ranked recommendations with scores and rationale), which clearly distinguishes it from siblings like search and list_servers that are direct retrieval 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?

Explicitly states when to use: when the user's request spans domains and you're unsure which server to use. It does not mention when not to use or name alternatives explicitly, but the use case is clear enough for an agent to decide without confusion.

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 side effects: tears down stale child connections, drops cached tool schemas, re-enumerates catalog, emits notifications, and notes the caveat about capabilities not being registered if the hub started with no exposed servers. This is rich behavioral context beyond a simple 'reload' statement. It doesn't mention auth requirements or rate limits, but for a reload tool those are less critical.

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-organized: main effect, use cases, parameter behavior, exposed-server behavior, and caveat. It's longer than the typical one-liner but every sentence adds information. The caveat is a bit long but valuable. Slight deduction for the caveat being somewhat verbose and the sentence about non-exposed servers being a bit dense.

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 optional parameter and no output schema, the description covers the main action, side effects, when to use, parameter semantics, and edge cases. The caveat about exposed servers and host reconnection is exactly the kind of context an agent needs to avoid incorrect assumptions. Nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter `server` is described in the schema. The description adds meaning by explaining the behavioral difference when `server` is set: only that server is reloaded, faster, no config re-read. This goes beyond the schema's 'only reload this server' and gives the agent a decision-relevant semantic.

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 ('reload'), a resource ('mcp-hub'), and enumerates concrete effects: re-reads config files, reconciles the server set, tears down stale child connections, and drops cached tool schemas. It clearly distinguishes itself from siblings like list_servers or get_server_tools by describing the reconciliation and cache-dropping behavior.

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 states when to use: after editing the hub's config, or after a child server's tools have changed. It also gives the alternative path: if `server` is given, only that server is reloaded (faster, no config re-read). It even notes a caveat about exposed servers and host reconnection, which helps an agent decide when reload is 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 provided, the description carries the full burden. It discloses the search scope, the dependency on previously loaded tools, and the ranking behavior. It does not explicitly state that this is a read-only operation, nor does it mention authentication or error behavior, but the semantics of a search imply safety.

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 with no filler. It front-loads the core purpose, then adds the important scope limitation. Every sentence contributes meaningful information, making it concise and well-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?

The tool is simple with two well-documented parameters, but there is no output schema and no annotations. The description explains the search scope and result type at a high level, but it does not describe the structure of individual hits or how 'limit' affects pagination. For a simple search tool this is adequate, though not fully complete.

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

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

Schema description coverage is 100%, and the input schema already documents 'query' as 'Keywords (space-separated)' and 'limit' as 'Max results (default 20).' The description adds no additional meaning to the parameters beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific action ('Search all configured servers and their known tools') and the result ('Returns ranked hits across server metadata and tool descriptions'). It clearly distinguishes this from sibling tools like list_servers or get_server_tools by describing the search scope and behavior, even without naming 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?

The description gives clear context: it searches all configured servers but only tool descriptions if tools were loaded via get_server_tools or call_tool, while server-level metadata is always searched. This implies when the tool is appropriate and includes an exclusion (servers with unloaded tools), though it doesn't explicitly compare against siblings like recommend_servers.

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