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

The readOnlyHint annotation already covers the safety profile; the description adds that it exposes response IDs for cleanup, but it does not disclose details such as ordering, pagination, or whether older entries are retained. This is adequate but not rich beyond the annotation.

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 packs in what is returned and a usage purpose. The phrasing 'What api_request has called' is slightly awkward, but there is no wasted 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?

For a simple optional-limit read-only log, the description states the returned fields and the intended cleanup workflow. The lack of an output schema makes a few details like list shape or ordering unknown, but nothing essential for invoking the tool 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 0% and the description never mentions the limit parameter. The name and schema constraints make limit mostly self-evident, but the description does not compensate for the missing parameter documentation as required at this coverage level.

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

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

The description identifies the tool as a record of what api_request calls have been made, naming endpoint, status, and response IDs, which clearly distinguishes it from sibling search/get tools. It lacks an explicit verb like 'list' or 'retrieve,' and 'api_request' is a slightly unclear referent, so it is not a 5.

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

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

The description gives a concrete use case: use the call log to clean up what was created. It does not name alternatives or state when not to use it, but for a simple read-only journal the context 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 readOnlyHint annotation already establishes the tool is non-destructive. The description adds output-related context such as 'danger level' and 'security alternatives', but it does not address tool-specific behaviors like rate limits or auth requirements. This adds some value beyond the annotation without contradicting it.

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 is front-loaded with the main purpose. It lists the output aspects without wasted words. It could mention the input format for the endpoint, but the schema covers that, keeping the text appropriately lean.

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 only 3 parameters, all fully described in the schema, and a read-only annotation, the description covers the tool's purpose and output scope reasonably well. The output schema is absent, so the description's enumeration of response aspects is helpful. It lacks explicit alternatives but is otherwise complete enough for straightforward 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 description coverage is 100%, with each parameter (endpoint, mode, depth) already documented including enums and defaults. The description's mention of 'compact, depth-limited' hints at the effect of depth/mode, but it does not add significant new meaning beyond the schema 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?

The description states a specific resource ('one endpoint') and the details it provides: parameters, request/response shapes, danger level, security alternatives, and URL. While it does not explicitly differentiate this tool from siblings like api_schema or api_get, the 'one endpoint' scoping and the list of output aspects make the purpose clear.

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

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

The description gives no guidance about when to use this tool versus the alternatives. It does not mention search, spec-level information, or other tools, and there are no usage prerequisites or exclusions. An agent must infer from the sibling names, which is insufficient.

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 annotations already declare readOnlyHint=true, and the description adds the useful constraint that the method is fixed to GET. It does not go further to explain auth selection, endpoint resolution, or response behavior despite openWorldHint being present.

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

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

Two short sentences with no filler. The core behavior and read-only constraint are front-loaded, and 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 generic GET-calling tool with five parameters and no output schema, the description is minimally viable but leaves out response format, error behavior, and sibling-tool routing. The annotations and schema cover safety and parameters, but not these operational 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 description coverage is 100%, and each parameter already has a descriptive schema (e.g., endpoint is 'METHOD /path'). The description itself adds no additional parameter semantics, 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 uses a specific verb ('Calls') and a specific resource ('a GET endpoint'), and notes that it returns the response. It clearly states what the tool does, but it does not distinguish this tool from siblings like api_endpoint or api_spec_info.

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

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

'Read-only: the method is fixed' implies this is for safe GET requests and not for mutations, giving some context. However, there is no explicit when-to-use guidance, no alternatives named, and no exclusions or conditions.

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 the tool read-only, and the description adds behavior beyond that: results are compact and depth-limited, path navigation is supported, and a usedBy field lists referencing endpoints. It does not describe error handling or full return structure, but for a read-only introspection tool the disclosed traits are useful and non-contradictory.

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-loads the core purpose, with the second sentence adding practical detail about path and usedBy. The first phrase is a sentence fragment ('A schema from components by name...'), which slightly hurts clarity, but there is no wasted 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 no output schema, the description partially compensates by mentioning usedBy, but it does not explain what the returned schema looks like, how mode affects the response, or error/not-found behavior. The input schema covers mode and depth, so the remaining gaps are moderate for an agent invoking 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?

Input schema covers 100% of parameters with descriptions and defaults, so the description does not need to carry parameter documentation. It reinforces `path` as a drill-down mechanism and depth-limited output, but adds no parameter semantics beyond what the schema already provides.

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 makes clear that the tool returns a schema from components by name and characterizes it as compact and depth-limited, which conveys the resource and format. It does not use a clear verb ('A schema...' rather than 'Gets a schema...') and does not explicitly differentiate from sibling tools like api_types or api_endpoint, but the usedBy detail adds a distinguishing capability.

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 implies when the tool is useful by saying `path` drills into nested fields and `usedBy` lists referencing endpoints, which suggests navigation and impact-analysis use cases. However, it gives no explicit when-to-use versus siblings such as api_types or api_endpoint, and no exclusions or 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?

Annotations only declare readOnlyHint, so the description carries the burden. It discloses output format ('One line per endpoint, no schemas'), result ordering ('Admin endpoints come last'), and a reliability caveat ('Summaries can be wrong — check the path and method'). These go beyond the annotation and help the agent set expectations.

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

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

Four short, information-dense sentences. The search scope is front-loaded, followed by output format, ordering, and a warning. No redundant wording; every sentence serves a 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?

For a search tool with six parameters and no output schema, the description covers key behavioral aspects: what is searched, result shape, ordering, and data reliability. It does not explain parameter semantics, but the schema itself documents several of them (query, has_body, include_admin) and the rest are fairly self-explanatory (method enum, limit bounds). Overall, an agent can call the tool correctly with this information.

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

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

The description does not add meaning to the tool's parameters (group, limit, query, method, etc.); it only lists the fields being searched, which relates to the query parameter but not to the other filters. Schema coverage is 67% for parameter descriptions, so the baseline is 3; the description neither compensates for uncovered parameters nor conflicts with 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 explicitly states it searches across method, path, operationId, summary, tags and parameter names, which is a specific verb and resource. It distinguishes this from sibling tools like api_endpoint (which likely retrieves a single endpoint) and api_spec_info by clarifying its search nature and result format ('One line per endpoint').

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

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

Usage is implied rather than stated: the description conveys that this tool finds endpoints through keyword search and warns to verify results, but it does not explicitly say when to prefer this over siblings or when not to use it. The statement 'no schemas' hints that schema retrieval belongs elsewhere, but this is not explicit.

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 is consistent with the readOnlyHint=true annotation — it describes a read of spec metadata, so no contradiction. It adds some context beyond the annotation by revealing the tool inspects security-scheme credential status and computes changes since the prior version. However, it does not disclose the refresh/caching behavior implied by the refresh parameter or any implications of exposing credential status.

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

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

One compact sentence of roughly 16 words with zero filler. The content categories are front-loaded, and every phrase earns its place by naming a distinct piece of information the tool returns.

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 optional parameter and no output schema, the description adequately covers the main content areas an agent needs to know. The refresh parameter behavior is left to the schema, and edge details like the meaning of 'changes since the previous version' are unspecified, but nothing essential is missing for a safe, non-destructive info 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 description coverage is 100% — the single optional boolean refresh parameter is fully documented in the schema with 'Revalidate the spec now'. The description adds nothing about the parameter, but the baseline of 3 applies because the schema carries the semantic weight; the description neither helps nor hurts here.

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

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

The description enumerates specific content categories — spec version, age, counts, groups, security schemes with credential status, and changes since the previous version — which clearly identifies what the tool returns and distinguishes it from siblings like api_schema, api_endpoint, and api_types. However, it lacks an explicit verb and reads as a content inventory rather than a statement of action, which costs it the top score.

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

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

No guidance is given on when to use this tool versus its six siblings (api_search, api_endpoint, api_schema, api_types, api_get, api_call_log). There is no when-to-use, when-not-to-use, or mention of alternatives, leaving the agent to infer selection from the content list alone.

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

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

The readOnlyHint annotation already indicates this is a safe read-only operation, and the description adds the detail that types are 'generated from the spec with @hey-api/openapi-ts', which is a light behavioral disclosure. It doesn't mention limitations, output format nuances, or whether generation fails, but it does not contradict the annotation either.

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

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

A single, front-loaded sentence provides all essential information without filler. It characterizes output, scope (endpoint), and generation source in a compact way that an agent can scan and act upon.

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

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

The tool is simple and has no output schema, so the description must sufficiently convey what the agent will receive. 'Ready-to-paste TypeScript types' communicates the format well, but the description does not explicitly mention the optional `include`/`name_prefix` parameters or how the output is structured, relying on schema defaults. For a type generation tool this is adequate but not fully comprehensive.

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?

Two of three parameters (`endpoint` and `name_prefix`) already have descriptions in the schema (67% coverage), so the base rating is a 3. The tool description adds value by listing 'request, response and parameters', which maps directly to the `include` enum and helps explain its semantics, but it does not deeply explain filtering, defaults, or how `name_prefix` affects output.

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 generates TypeScript types for an endpoint, using the specific verb 'generates' (implied by 'Ready-to-paste') and naming the resource (types for request, response, and parameters). It distinguishes the purpose from siblings like api_schema, which would return raw schemas, but it does not explicitly name other siblings or state what this tool is not.

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 purpose statement implicitly suggests when to use it (when you need TypeScript types), but there is no explicit guidance about when not to use it, nor any mention of alternative tools like api_schema or api_endpoint. It leaves the choice of tool inferable from the context provided by sibling names, but without direct comparison.

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