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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers substantial behavior on top: the 50-line cap with true total and endpoint count, the close-alternatives fallback, the response format, and case-insensitivity. This is exactly the contextual value annotations cannot provide.

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 is front-loaded in the first sentence, and every subsequent sentence earns its place (format, cap, successor tool, fallback). Slightly long but information-dense with no filler.

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

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

For a search tool with an output schema, the description covers everything an agent needs: result format, line-by-line fields, pagination/truncation honesty, endpoint-count reporting, and downstream integration. Nothing actionable 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% — both parameters are documented, including case-insensitivity on field_name. The description adds the common-names-capped behavior but otherwise relies on the schema, which is the appropriate division of labor at the baseline.

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 ('locate') and resource ('field by name across every endpoint'), and adds the discriminator-variant nuance that shows real scope understanding. This cleanly separates it from siblings like list_endpoints and get_field_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 how output feeds into get_field_schema ('Paths from here can be passed straight to'), connecting this tool to its successor. It does not enumerate when-not-to-use cases, but the purpose and output semantics make the use case unambiguous.

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 provide readOnlyHint, idempotentHint, and destructiveHint all true, indicating a safe, read-only operation. The description adds valuable context that the documentation is a point-in-time copy, not live, which is critical for an agent to avoid relying on stale info. This goes beyond the annotations and is a key behavioral insight. The description is consistent with annotations, so no contradiction.

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 straight purpose, then adds the crucial caveat about the documentation being a point-in-time copy. Every sentence adds value with no fluff. The structure is ideal: clear statement first, followed by actionable 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?

The description is complete for this zero-parameter tool. It explains what the tool returns (one line per application with API version, scrape time, endpoint/guide counts) and provides a clear use case (checking before trusting answers about recent changes). Given the simplicity and output schema present, nothing is missing for an agent to correctly invoke this tool.

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

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

The tool has zero parameters, making parameter semantics a non-issue. With no parameters to document, the baseline is 4, indicating that the description does not need to compensate for missing parameter info. The description is sufficient for an agent to call the tool without any 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 clearly states the tool reports what documentation the server is serving crumb, and specifies the content: API version, scrape time, and counts of endpoints and guides. It is distinct from siblings because it provides an overview of the documentation set, whereas siblings like get_endpoint or get_guide focus on specific items. However, it could be slightly more explicit that it summarizes the whole documentation corpus vs. individual items.

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 advises checking this tool before trusting answers about recent API changes, making the usage context clear. It does not explicitly mention when not to use it or name alternatives, but the implicit guidance is strong enough for an agent to decide when this overview is appropriate. It lacks explicit exclusion criteria but is still effective.

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 mark this as read-only and idempotent, and the description adds substantial behavioral context: it returns readable folded text, folds at three levels deep, may be tens of thousands of characters, and returns close matches for unknown slugs. This goes well beyond the annotation signal and prepares the agent for output size and error 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 front-loaded with the core purpose, then covers output format, size, the alternative tool, and error behavior in a compact, well-organized set of sentences. Every sentence earns its place and no information is repeated or wasted.

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

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

Given that an output schema is present, return-field documentation is not the description's job. It covers tool scope, output format, scale warning, a recommended sibling for narrower use, and unknown-slug behavior, making it complete for an agent to select and invoke the tool confidently.

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 full, detailed descriptions for both parameters, so the baseline is a 3. The description adds extra behavioral nuance by mentioning the large-output problem and the get_field_schema fallback, and by explaining that unknown slugs still produce useful matches. It does not deeply re-document the parameters, but what it adds is meaningful.

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: 'Get everything documented about one endpoint' and enumerates exactly what is included (method, path, parameters, request body, response fields). It also implicitly distinguishes itself from siblings by pointing to get_field_schema for narrower field-level queries, so an agent can tell which tool fits.

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

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

The description explicitly says to use get_field_schema when you already know the specific field, giving a concrete when-to-use alternative. It also warns that large endpoints produce very large output, and explains that an unknown slug returns close matches rather than an error, which helps an agent anticipate and handle edge cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description aligns with them. It adds genuinely useful behavioral detail beyond those annotations: substring matching, grouping by path, nested paths, and the ability to span applications.

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

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

The description is compact and front-loaded: the purpose is stated first, then return shape, then matching behavior. Every sentence adds value without repetition or filler.

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

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

For a tool with one parameter, clear annotations, and an output schema, the description is complete from an agent's perspective. It explains what will be returned, how matching works, and what the grouping will look like, without needing to restate schema details.

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 resource parameter is already described with examples. The description adds important semantic detail beyond the schema: matching is a substring, nested paths are included, and one query can span applications, clarifying scope significantly.

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 object: 'See every operation on one resource at once, grouped by API path.' It immediately distinguishes itself from tools like get_endpoint by emphasizing that all verbs on a resource are returned together rather than one at a time.

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 communicates the intended use case: when you want all operations on a resource visible together, or when matching a path substring to find nested paths across applications. It does not explicitly name sibling alternatives or provide exclusions, but the context is strong enough for an agent to select it appropriately.

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 cover read-only, idempotent, and non-destructive hints. The description adds valuable behavioral context: it describes the return format (heading + single code block), clarifies that placeholders (host addresses, site ids, API keys) are to be filled in, and notes that bodies use schema default values. This goes beyond annotations and gives the agent a clear picture of what to expect.

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

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

The description is three sentences, front-loaded with the core purpose, then adding necessary context and usage guidance. There is no fluff or repetition. Every sentence earns its place: the first states the function, the second describes the response format and placeholders, the third covers usage and error handling.

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 an output schema exists (per context signal), the description need not detail the full response structure. It covers the essential aspects: what the tool returns, how placeholders work, how to handle the payload case, and what happens on invalid pairs. It also names alternative tools for when this one is insufficient. The tool is simple and the description is complete for an agent to call it correctly.

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

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

The input schema has 100% coverage with clear descriptions for all three parameters (slug, language, mode), so the baseline is 3. The description mentions language and mode indirectly (e.g., 'in one language' and the error condition on language/mode pairs) but does not add significant new meaning about parameter syntax or valid values beyond what the schema already provides. It adds context about how parameters affect the output but not enough to justify a higher 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?

The description opens with a precise statement: 'Get a runnable request for one endpoint, in one language, as published by Ubiquiti.' This identifies the exact verb, resource, and scoping (one endpoint, one language). It clearly differentiates from siblings like get_response_sample (which likely returns a sample response) and get_endpoint (which likely returns the endpoint definition) by focusing on the runnable request.

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

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

The description gives explicit when-to-use guidance: 'Bodies show the schema's default values, not a worked example — combine with get_endpoint or get_field_schema when the payload matters.' This tells the agent to use alternative tools when the payload is important. It also explains the error behavior: 'If the requested language and mode pair does not exist, the reply lists the pairs that do instead of failing,' which clarifies what happens on invalid input.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context: it's a lightweight subtree fetch versus a large schema, and it accepts find_field output paths directly. This is meaningful but not rich — no mention of failure modes, pagination, or edge cases, which the annotations don't require given the read-only nature.

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: core purpose, usage guidance with sibling differentiation, and input-compatibility note. Front-loaded with the primary function and zero 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?

Complete for a read-only tool with a defined output schema (so return values need no explanation), 100% parameter coverage, and annotations that establish the behavioral profile. Purpose, when-to-use, and input compatibility are all addressed — nothing an agent needs to call it correctly 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%, so both slug and field_path are fully documented with examples in the schema. The description adds one genuinely useful note — 'Paths from find_field output work directly' — which clarifies the expected format of field_path beyond the schema. This is a real but marginal addition over the schema's baseline.

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 (drill into/get) and resource (a field's schema within an endpoint), and the second sentence explicitly contrasts it with fetching the full 70KB endpoint schema — which differentiates it from the sibling get_endpoint. An agent can tell it apart from its siblings without opening schemas.

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 'Instead of fetching the full 70KB endpoint schema, use this to get just the subtree you need' line gives clear context for when to choose this tool over a full-schema fetch. It also notes compatibility with find_field output. However, it doesn't name alternatives explicitly (e.g., get_endpoint) or state when not to use it beyond the size heuristic.

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 goes well beyond the annotations, disclosing output shape (markdown with title and source URL), resolution order (slug first, then title), and ambiguity handling (lists matches and asks rather than guessing). These are non-obvious behaviors an agent needs to invoke the tool correctly.

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 front-loads the core purpose in the first sentence, then packs behavior, return value, and usage conditions into two compact sentences with no repeated information 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?

The description covers what the tool returns, how topics are resolved, what happens in ambiguous cases, how to list available content, and why this tool matters relative to schema-based siblings. Combined with the annotations and schema, nothing essential is missing 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?

The schema already documents both parameters at 100% coveragecars, but the description adds meaningful semantics beyond the schema: the topic resolution order, the ambiguity behavior, and the fact that omitting the topic produces a list of all guides. This is valuable, hence above baseline, though not extensive.

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: 'Read a prose guide page,' and enumerates the contents (filtering syntax, error handling, response formats). It implicitly distinguishes itself from schema-focused sibling tools like get_endpoint and find_field by positioning this as the prose/conventions companion to those structured references.

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 clear operational guidance: omit the topic to list available guides, use the app filter when needed, and expect slug-first resolution. It explains when these pages matter ('carry conventions that endpoint schemas assume') but does not explicitly name an alternative tool or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds value by disclosing placeholder values, exact matching to documentation, and that missing samples are communicated plainly. It does not mention auth or rate limits, but these are not strongly demanded given the safe read-only profile.

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 clear purpose, followed immediately by return behavior and a routing note. Every sentence contributes either scope, capability, expectation-setting, or a pointer to the alternative tool.

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

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

There is an output schema, one required parameter documented fully, and complete annotations covering safety and idempotence. The description adds availability expectations and points to get_endpoint for schema details, which leaves an agent with enough to 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 description coverage is 100% and includes a concrete slug example, so the parameter meaning is already fully established. The description adds only broad context that the tool targets 'one endpoint', which does not go 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?

Description states a specific verb and resource: 'Get the sample response body published for one endpoint' and clarifies that it returns raw JSON as shown in documentation. It also differentiates itself by directing field-by-field schema needs to get_endpoint, so an agent can pick the right 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?

The description explicitly gives context for expected behavior: about two-thirds of endpoints have a sample and the rest say so plainly. It also names the alternative, get_endpoint, for schema/type/optional-field detail, making the choice between sibling tools 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the 200-line cap, the withholding message, and the rejection of unknown filter values. It doesn't describe pagination or the exact output schema, but the output schema exists and the description covers the key non-obvious behaviors.

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: it opens with the core purpose and output format, then covers limits, alternatives, and error behavior in three sentences. Every sentence earns its place with no redundancy.

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

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

For a read-only list tool with an output schema and full parameter documentation, the description is nearly complete. It covers the cap, the alternative tool, and error behavior. The only minor gap is that it doesn't explicitly describe pagination or how to request more than 200 lines, but the description says the reply says how many were withheld and which filters would narrow it, which is sufficient guidance.

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 the schema already documents both parameters (app and method) with their allowed values. The description adds the behavior of unknown filter values being rejected by name, which is useful, but it doesn't add much beyond the schema's parameter documentation. 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 states a specific verb ('Browse') and resource ('endpoint catalogue'), and specifies the output format (one line per endpoint with method, path, slug, title). It also distinguishes itself from search_endpoints by noting that search ranks by relevance, so an agent can clearly tell this is the list-all/browse 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?

The description explicitly says when to use this tool vs alternatives: 'For finding a specific endpoint, search_endpoints ranks by relevance instead.' It also explains the 200-line cap and that unknown filter values are rejected by name, giving clear behavioral context for when to use it.

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

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

The description discloses several non-obvious behaviors beyond the annotations: it returns at most ten matches, ranking by relevance, uses fuzzy matching with a floor (no results if nothing resembles the query), and rejects unknown filter values. Annotations already declare readOnlyHint and idempotentHint, so the description adds useful operational context 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 tight and well-organized: purpose statement, output format, matching behavior, routing to get_endpoint, and filter error handling. Each sentence earns its place, and key info is front-loaded. No redundant or vague phrasing.

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 search tool with an output schema, the description covers the result shape, relevance cap, fuzzy matching floor, and the path to get_endpoint. It does not explicitly differentiate from list_endpoints or explain error scenarios beyond unknown filters, but given the output schema and annotations, it is sufficiently complete for an agent to call 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%, with each parameter (query, app, method) having its own description. The tool description adds minimal extra semantics beyond the schema—mostly restating that app and method act as filters. It does add the note that unknown filter values are rejected, but this is behavioral rather than parameter-specific. 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 opens with a specific verb and resource: 'Find endpoints by name, path fragment, method or description.' It clearly distinguishes the tool from siblings like list_endpoints by focusing on search and relevance ranking, and it explicitly routes to get_endpoint for full schema details.

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 implicitly guides usage by saying 'Pass a result's slug to get_endpoint for the full schema,' indicating when to use get_endpoint. However, it does not explicitly state when to prefer search_endpoints over list_endpoints or other siblings, leaving the selection partially to inference.

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