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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds specific behavioral context by listing the data categories returned (resource usage, running services, detected issues), which helps set expectations beyond the schema. This is meaningful extra context, though it does not address pagination or output structure (mitigated by the output schema).

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

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

The description is a single, compact sentence that front-loads the action and resource, then adds three specific data categories. Every word earns its place; no filler or redundant repetition of the tool name.

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 one well-documented parameter, an output schema present, and annotations indicating a safe read operation, the description is sufficient. It clearly conveys the tool's scope and output categories, making it complete for an agent to select and invoke 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% for the single parameter, including an example value. The description's phrase 'for a specific host' reinforces the parameter's purpose but does not add new meaning beyond the schema. Baseline 3 is appropriate since the schema already provides full documentation.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource as 'detailed health data for a specific host,' enumerating resource usage, services, and issues. This distinguishes it from sibling tools like 'get_host_info' (basic info) and 'explain_service_health' (service-level focus).

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 use for a specific host's health details, but does not explicitly state when to prefer this over alternatives like 'get_host_info' or 'explain_service_health.' There is no exclusionary guidance, so the agent must infer context from the tool name and sibling set.

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 already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description adds context about the data content (status, location, dependencies, issues) but does not disclose any behavioral traits such as response format, pagination, or error handling beyond what the output schema likely covers.

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

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

The description is a single, well-structured sentence that front-loads the primary action ('Get detailed health data') and then specifies what that includes. Every word is informative with no redundancy or verbosity.

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 read-only tool with one parameter and an output schema, the description is sufficiently complete. It explains the key purpose and content areas, and the output schema covers return value specifics. No additional prerequisite or edge-case information is necessary for correct invocation.

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% with the service_name parameter having a clear description and example. The tool description does not add any further parameter semantics beyond restating that it applies to a specific service.

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

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

The description clearly states the tool's function: 'Get detailed health data for a specific service' and lists the key components (status, location, dependencies, issues). This differentiates it from siblings like get_service_info (basic info) and show_dependency_chain (only dependencies).

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 when detailed health data is needed for a specific service, but it does not explicitly state when to use this tool versus alternatives like get_service_info or show_dependency_chain. No exclusion or when-not guidance is provided.

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?

Beyond the readOnlyHint annotation, the description discloses significant behavioral details: stripping navigation/ads/boilerplate, blocking loopback/link-local/cloud-metadata targets, conditional blocking of private targets via FETCH_ALLOW_PRIVATE, and re-validation of redirects at every hop. These are non-obvious behaviors that help the agent understand side effects and constraints.

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 front-loaded with the core purpose in the first sentence, followed by a compact paragraph of essential constraints. Every sentence provides unique value—no fluff or repetition of schema or annotation content.

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

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

With a single parameter, a clear output (markdown), and thorough behavioral constraints, the description is complete for an agent to decide when and how to use the tool. The output schema handles return-value details, so the description focuses on input constraints and processing behavior, which it does thoroughly.

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

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

The schema only describes 'url' as 'URL to fetch and extract content from.' The description adds crucial meaning: allowed protocols (http/https), blocked address categories, environment variable effect, and redirect behavior. This goes well beyond the schema's bare parameter description.

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

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

The description opens with a specific verb and resource: 'Fetch a web page and extract its content as clean markdown.' This clearly states the tool's function and differentiates it from all sibling tools, which focus on docs, services, and infrastructure data rather than web fetching.

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 context by stating what the tool fetches (web pages) and includes constraints like 'Only http/https URLs are fetched.' It does not explicitly mention alternatives or when not to use it, but given the entirely different sibling tools, the intended use is clear.

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

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

The description discloses that partial results are returned if individual services are unreachable, which adds valuable behavioral context beyond the readOnlyHint annotation. It also sets expectations by listing the components included.

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

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

The description is a single, well-structured sentence that front-loads the tool's purpose and uses a colon-separated list for specifics. It is concise with no wasted words.

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

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

For a zero-parameter, read-only tool with an output schema, the description covers purpose, content, and a key behavioral caveat. It is slightly incomplete in not situating the tool among sibling overview tools, but overall it is sufficient for selection and invocation.

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

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

The tool has no parameters, so the schema is inherently 100% covered. The zero-parameter baseline of 4 applies; the description adds no parameter information but none is needed.

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

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

The description clearly states the tool's function as a complete homelab overview, enumerating specific data categories (host health, container counts, storage, media streams, errors, speed test results). This differentiates it from narrower sibling tools like get_service_info or get_media_overview.

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 a general overview use case but does not explicitly state when to use this tool versus alternatives such as get_infra_overview or get_media_overview. No exclusions or comparisons are provided.

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 already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context about the returned data (specs, role, OS, services) but does not go beyond that into behavior like freshness or aggregation specifics. With annotations covering safety, this is adequate without being rich.

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

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

The description is a single, front-loaded sentence that efficiently conveys the purpose and return content. There is zero superfluous text, and every phrase adds value.

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

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

Given the simple tool with one parameter, good annotations (readOnlyHint), and the presence of an output schema, the description provides sufficient context. It states what the tool returns in broad terms, and the output schema fills in the detailed structure. No further information is needed for an agent to select and invoke this 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?

The input schema has 100% coverage with a well-described parameter including examples. The tool description reinforces the parameter meaning by saying 'by name or IP', but does not add significant new semantics beyond the schema. The baseline of 3 applies since schema 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 clearly states the verb 'Look up' and the resource 'host' by name or IP, and lists the specific return data (specs, role, OS, services). It distinguishes itself from siblings like get_service_info and get_ip_info by focusing on the entire host.

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 the use case: when you need host details via name or IP. However, it does not explicitly mention alternatives or situations where a sibling tool might be more appropriate, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is transparent. The description adds useful context about the covered areas but does not disclose any behavioral nuances such as data freshness, aggregation limits, or how statuses are determined. It neither contradicts nor significantly extends the annotations.

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

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

The description is a single sentence that front-loads the tool's purpose ('Infrastructure overview') and then lists key data categories. Every word earns its place with no redundancy or filler.

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

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

Given the zero-parameter input and the presence of an output schema, the description sufficiently covers the tool's scope by enumerating all major infrastructure areas. It provides a complete picture of what the overview includes, making it adequate for an agent to decide invocation and understand the return scope.

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

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

The tool has zero parameters, so the schema already fully describes the absence of inputs. The description does not need to explain parameter semantics, and the baseline for zero-parameter tools 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 clearly states the tool provides an 'Infrastructure overview' and enumerates specific topics (Proxmox node status, Docker counts, storage, CrowdSec, NPM). This distinctively differentiates it from sibling overview tools like get_homelab_overview and get_media_overview by focusing on infrastructure components.

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

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

The description implies the tool is used when an infrastructure-level summary is needed, but it does not explicitly state when to use it over siblings, nor does it mention exclusions or alternative tools. The usage context is inferable but not directly guided.

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

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

The annotation already declares readOnlyHint=true, and the description adds that it returns the host and all services, which is useful but not extensive. It does not contradict annotations, and for a simple read-only lookup with an output schema, this is adequate but not deeply transparent.

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

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

The description is a single, focused sentence that front-loads the action and result. Every word contributes meaning, with no redundancy or filler.

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

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

This is a simple tool with one parameter, a complete input schema, an output schema, and annotations indicating it is read-only. The description sufficiently covers the tool's purpose and return content, making it complete for its 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?

The input schema provides full description coverage for the ip parameter, including an example and shorthand notation. The description adds minimal semantic context beyond the schema, 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 uses a specific verb 'Reverse-lookup' and clearly identifies the resource (an IP address) and the returned content (host and all services at that IP). This effectively distinguishes it from sibling tools like get_host_info and get_service_info by focusing on the IP-level query.

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

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

The description implies when to use the tool: whenever you need to reverse-lookup an IP address. However, it does not explicitly state when not to use it or mention alternatives, leaving usage guidance implied rather than direct.

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 already declare the tool as readOnlyHint=true, so the safety profile is known. The description adds the specific data domains covered, but doesn't mention any additional behavioral aspects like data freshness, caching, latency, or potential side effects. This adds some value beyond annotations but is not rich behavioral 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?

The description is a single sentence that front-loads 'Media overview' followed by a concise list of included services. Every word contributes to understanding the tool's scope, with no redundancy or filler. It's well-sized for the complexity.

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

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

With an empty input schema and an output schema present, the description sufficiently scopes what the tool covers. It clearly enumerates all media services included, making it easy for an agent to decide when to select it. It could mention aggregation across services, but that's a minor gap.

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

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

The tool has zero parameters, so schema coverage is 100% by definition. The baseline for zero-param tools is 4; the description doesn't need to explain any parameters and doesn't attempt to. No parameter information is missing.

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

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

The description clearly states the tool's purpose: providing an overview of media-related services. It lists specific sub-services (Plex, Sonarr/Radarr, Transmission, Overseerr, Prowlarr), which distinguishes it from sibling overview tools like get_homelab_overview and get_infra_overview. The verb 'overview' and resource 'media' are specific and unambiguous.

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

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

The description implies the tool is for getting a snapshot of media service status, and the list of included items makes its scope clear. It doesn't explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to decide between this and other overview tools. No exclusions are provided.

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 declare readOnlyHint=true and openWorldHint=false, and the description is consistent with these. The description adds behavioral context by specifying exactly what fields are returned (host, port, stack, domain, role, co-located services), which goes beyond the annotations and schema structure itself.

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-load the action and then enumerate outputs concisely. Every sentence earns its place with no filler, redundancy, or repetition of schema details.

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 low-complexity tool with a fully documented required parameter, an existing output schema, and safety annotations. The description adequately covers purpose and provides a useful output preview; given the rich structured context, nothing more is needed.

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 covers the single required parameter fully (100% coverage) with an explicit description and examples of valid service names. The description's phrase 'by name' reinforces that name is the exact lookup key, adding marginal meaning but not materially extending 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 uses a specific verb ('Look up') with a clear resource ('a service by name') and enumerates the return fields (host, port, stack, domain, role, co-located services), which distinguishes it from sibling lookup tools like get_host_info and get_ip_info. The scope is precise and immediately idsss the tool's identity.

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 usage scenario is implied ('look up a service by name') but the description does not explicitly state when to use this versus siblings such as get_host_info, get_ip_info, or explain_service_health. No alternatives or exclusions are named, leaving the differentiation to the reader.

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

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

The description adds useful context beyond annotations by specifying what gets refreshed and that it returns a summary of changes. Annotations already cover idempotency and destructiveness, and the description does not contradict them. It does not mention rate limits or failure modes, but does enough with the annotation baseline.

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 sentence that front-loads the action and specifies both the affected resources and the return value. It contains no filler or redundant information.

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

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

For a no-argument tool with an output schema, the description sufficiently states what it does and what it returns. There are no additional parameters or prerequisites to document, so the description is complete for invocation.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The description is not required to add anything, and an empty schema needs no compensation. A baseline of 4 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 a specific verb ('Force an immediate refresh') and resource ('documentation, Docker stacks, and vault notes from Gitea repositories'). It distinguishes itself from sibling tools like search_docs and refresh_registries by naming the exact content being refreshed.

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

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

The description implies the tool is for forcing an immediate refresh when up-to-date data is needed, but it does not explicitly mention when not to use it or provide alternatives like refresh_registries. Usage context is present but lacks exclusions or comparisons with sibling tools.

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

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

The description adds valuable context beyond annotations by listing the external sources, emphasizing the 'force' aspect (a forceful update), and indicating a summary of changes is returned. It does not contradict the idempotentHint or destructiveHint annotations.

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

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

The description is a single, focused sentence that front-loads the core action, enumerates sources efficiently, and states the return value. Every phrase adds value without redundancy.

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

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

For a zero-parameter tool with an output schema, this description is complete. It explains what the tool does, which sources it touches, and what it returns, covering all essential context needed for correct invocation.

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 zero parameters, the baseline is 4. The description correctly has no parameter details, and the schema fully covers the (empty) parameter list. No further semantic explanation is needed.

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

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

The description uses a specific verb ('refresh') and resource ('service and host registries'), and explicitly lists all live API sources, distinguishing it from sibling tools like refresh_docs. It fully clarifies the tool's scope and action.

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 this tool—when an immediate refresh of registries is needed—but does not explicitly mention exclusions or direct alternatives. Since no comparable sibling exists for this exact action, the context is sufficient, though not exhaustive.

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

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

The description adds behavioral context beyond the readOnlyHint and openWorldHint annotations by explicitly stating the return format (matching paragraphs with source file and section). It does not contradict annotations and provides useful information about what the tool outputs.

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, front-loaded with the verb and resource, and contains no filler. Every word adds value.

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

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

For a simple 2-parameter search tool with read-only annotations and an output schema, the description adequately covers purpose, scope, and return format. There are no significant 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?

The input schema already provides descriptions for both parameters (query and max_results), covering 100% of them. The tool description adds no additional parameter-specific semantics, so the baseline score 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 clearly states the tool performs full-text search across all homelab documentation and specifies what it returns (matching paragraphs with source file and section). This distinguishes it from sibling tools like get_service_info or fetch_page, which have different purposes.

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

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

The description implies usage for searching documentation but does not explicitly state when to use it versus alternatives or any exclusions. The scope is clear ('across all homelab documentation'), but there is no explicit guidance on when not to use it or which sibling to choose 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is established. The description adds value by explicitly stating that the tool returns which data sources are reachable and which are not, providing additional behavioral context beyond the annotations. No contradictions exist.

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 concise, two-sentence structure that front-loads the primary purpose and immediately clarifies the return value. Every word serves a clear function, with no redundancy or filler.

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

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

Given the tool has no parameters and an output schema exists (as indicated in context signals), the description sufficiently covers the tool's purpose and output. For a simple, parameter-less status check, the description explains what it does and what it returns, making it complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on the tool's behavior and output without introducing any parameter-related confusion.

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

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

The description clearly states the tool's function: 'Check connectivity and freshness status for all configured services' and specifies the output: 'Returns which data sources are reachable and which are not.' This distinguishes it from sibling tools like what_changed_last_24h or get_service_info by focusing on data source reachability and freshness.

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

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

The description implies the tool is used when checking connectivity or freshness of data sources, but it lacks explicit guidance on when to use it versus siblings or when not to use it. There are no alternatives mentioned, making the usage context only implicit.

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 already indicate readOnlyHint=true and openWorldHint=false, which provide a baseline safety profile. The description adds meaningful behavioral context by detailing what the response contains (what it runs on, depends on, ingress, storage), going beyond a trivial 'shows dependencies'. It does not mention limitations like recursion depth or error handling, but the annotation coverage lowers the bar and the added return-type detail is valuable.

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, information-dense sentence structure that front-loads the core purpose and then lists the response categories after a colon. Every word earns its place; there is no fluff or redundancy, making it highly concise yet complete.

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

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

Given the tool's modest complexity (one parameter), the presence of an output schema, and annotations that declare read-only safety, the description adequately covers the essential context. It specifies what the tool returns without needing to detail return value structure. A minor gap is the lack of mention of any limitations (e.g., entity types not covered), but overall it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with the 'entity' parameter thoroughly described as accepting service names, hostnames, or domains. The description does not add additional parameter-level detail beyond the schema, so the baseline of 3 is appropriate. No extra semantics are provided to clarify edge cases or formatting.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Show the full dependency chain for any homelab entity.' It enumerates the exact types of information returned (run-on, dependencies, ingress, storage), which distinguishes it from sibling tools that focus on individual entity details or health summaries.

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

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

The description provides clear context for when to use the tool by explicitly defining its scope ('full dependency chain'), which implies its use for relationship discovery. It does not explicitly exclude alternatives or name sibling tools, but the purpose is specific enough that an agent can infer appropriate use cases 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?

Annotations already declare readOnlyHint=true, and the description adds value by specifying the full range of event types included (alerts, target flaps, failed checks, security bans, expiring certs, backup issues). It does not mention pagination or response format, but the output schema exists and this is a read-only tool with minimal behavior.

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

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

The description is a single sentence, front-loaded with the main operation ('Get a unified timeline'), followed by a concise list of included event types. No unnecessary words or repetition.

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: one optional parameter, read-only, with an output schema available. The description sufficiently communicates the purpose and content coverage. The parameter schema explains the time window, and annotations capture safety. 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 description coverage is 100%: the only parameter 'hours' is fully described with its default value. The tool description does not add any further parameter explanation, but the schema fully covers it, 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 uses a specific verb 'Get' and clearly identifies the resource: a unified timeline of recent events across the homelab. It enumerates specific event types (alerts, target flaps, failed checks, security bans, expiring certs, backup issues), which distinguishes it from sibling tools like what_needs_attention or get_homelab_overview.

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

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

The description implies when to use this tool (to see a unified timeline of recent events), but it does not explicitly state when NOT to use it or name alternative tools. There is no exclusion guidance, but the context is fairly clear from the description.

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 already indicate readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds value by disclosing the scope of the check (multiple subsystems) and the output behavior (verdicts sorted by severity), which goes beyond the annotations without contradicting them.

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 extremely concise: one main sentence listing what is checked and one parenthetical exclusion with an alternative. Every word earns its place, and the structure front-loads the core purpose.

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 parameters and an output schema present, the description provides all necessary context: the tool's function, its data sources, the return style (prioritized, severity-sorted verdicts), and an explicit exclusion with a fallback tool. It is fully complete for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, making parameter-specific guidance unnecessary. The schema is empty and coverage is effectively 100%. The description adds no parameter details because there are none; a baseline of 4 is appropriate for a no-argument tool.

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

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

The description uses a specific verb phrase 'Get a prioritized list of things that need attention right now' and enumerates exactly which sources it checks (host resources, Prometheus, cron, CrowdSec, SSL). It distinguishes itself from siblings by noting what it does not cover and providing a direct alternative, making the purpose unambiguous.

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

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

The description explicitly states what the tool covers, what it does not cover ('Does not check backups'), and points to a sibling tool ('use get_pbs_status') as the alternative. This provides clear when-to-use and when-not-to-use guidance.

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