Kudosity

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

Annotations already provide destructiveHint=true, so the description's lack of behavioral details is acceptable. The description does not contradict annotations and adds no extra context beyond what is already in the structured fields.

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 with no waste. It is front-loaded and efficiently conveys 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?

The description covers the basic purpose but does not explain the return value or behavior (e.g., HTTP response, errors). Given no output schema, more detail would be helpful for a tool that executes requests.

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 baseline is 3. The description does not add additional meaning to the parameters 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 'Executes an API request with a given HAR request object' clearly states the tool's action and input format. The tool name and description distinguish it from siblings that list or search specs/endpoints.

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 that users should first use 'list-specs' or 'search-endpoints' to find a title, but it does not provide explicit guidance on when to use this tool vs siblings, nor does it mention when not to use it 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 indicate readOnlyHint=true, so the description adds value by mentioning that details include 'security schemes and servers'. However, it does not disclose other behavioral traits like error handling or rate limits. The description adds some context beyond annotations but is not comprehensive.

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 concisely communicates the tool's purpose. Every word serves a purpose, and there is no redundancy or wasted verbiage.

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 complexity (3 parameters, no output schema) and presence of annotations, the description is minimally adequate. It mentions return content (security schemes and servers) but lacks details on error scenarios, prerequisites (e.g., valid spec title), or full return structure. This leaves some gaps for an agent.

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 each parameter is already documented. The tool description does not add additional meaning to the parameters beyond what the schema provides, resulting in no extra semantic value.

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

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

The description clearly states 'Gets detailed information about a specific API endpoint', indicating a specific resource and action. However, it does not explicitly differentiate from siblings like list-endpoints or search-endpoints, lacking clarity on when to use this tool over others.

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 usage guidance is provided. The description does not specify when to use this tool versus alternatives (e.g., list-endpoints for listing, search-endpoints for searching). An agent would need to infer usage from context.

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 (safe read) and openWorldHint=false. The description does not add new behavioral details (e.g., pagination, rate limits). It accurately describes the function but adds no extra transparency beyond 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 two sentences with no wasted words. It front-loads the main action ('Lists all API paths...') and efficiently explains follow-up usage. Highly concise.

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 single-parameter design and good annotations, the description covers the core functionality and workflow connection. It does not describe output format or pagination, but for a list tool with no output schema, this is adequate.

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 one parameter fully documented in the schema (description explains how to find the title). The tool description does not add parameter-specific semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists all API paths and HTTP methods with summaries, organized by path. It also specifies that results can be passed to 'get-endpoint', distinguishing it from sibling tools like 'get-endpoint' (details) and 'search-endpoints' (filtered list).

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 indirectly guides usage by noting that results feed into 'get-endpoint' and that parameter 'title' can be obtained via 'list-specs' or 'search-endpoints'. However, it does not explicitly state when to use this tool versus 'search-endpoints', which might offer filtering.

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 the hint to use the title, but annotations already declare readOnlyHint=true. No contradiction, but minimal additional 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?

Two short sentences with no wasted words. Front-loaded with the main action and concise usage advice.

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, zero-parameter tool with readOnlyHint and no output schema, the description is complete. It explains what it does and how to use the result.

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?

Zero parameters; baseline score of 4 applies. The description adds usage context about selecting a spec from the output, which goes beyond the empty schema.

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

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

The description clearly states it lists all available OpenAPI specs with a specific verb and resource. It distinguishes from sibling tools like list-endpoints by focusing on specs themselves.

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 suggests using the title to select a spec but does not explicitly differentiate from siblings or provide when-not-to-use guidance. Usage is implied rather than 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?

Annotations indicate readOnlyHint=true, and the description aligns by describing a read-only planning operation. It adds context about asking questions and returning a structured plan, which goes beyond the bare annotation. No contradictions.

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

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

The description is two sentences, concise and front-loaded. Every sentence adds value: the first defines the purpose, the second specifies the output and behavior. No redundancy or waste.

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 no input parameters, no output schema, and a simple read-only planning task, the description covers what the tool does, its output, and how it behaves (asking questions). It is fully complete for the tool's 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 tool has no parameters (100% schema coverage naturally), so the baseline is 4. The description does not need to explain parameters but effectively focuses on the tool's purpose and output, which 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 determines the correct Kudosity API version per operation based on user intent and auth, and returns a routing plan. It distinguishes itself from siblings like execute-request or list-endpoints by focusing on planning rather than execution or discovery.

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 using this tool before executing requests to decide versioning, and explicitly instructs to ask clarifying questions if info is missing. It could be improved by stating when not to use it (e.g., if version is already known) or naming alternatives, but the guidance 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 and openWorldHint=false. The description adds that the search is 'deep' and covers paths, operations, and parameters, but does not detail pagination, result limits, or what 'deep' entails. For a search tool, this is adequate but not exceptional.

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

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

Two sentences, no unnecessary words. The first sentence defines the action, the second provides usage guidance. Front-loaded with 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?

The description covers primary use and chaining guidance, but lacks details on return format or result structure. Given no output schema, more information about what constitutes a 'relevant' endpoint would improve completeness.

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

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

Schema coverage is 100%, with a single 'pattern' parameter described as 'Search pattern (case-insensitive)'. The description adds the case-insensitivity detail, but no further semantics like allowed wildcards or format. Thus, it adds marginal value over 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 clearly states the tool performs a deep search through paths, operations, and parameters to discover API endpoints. It uses a specific verb ('search') and resource ('API endpoints'), and effectively distinguishes from sibling tools like 'get-endpoint' and 'list-endpoints' by emphasizing keyword-based discovery.

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 explicit usage scenarios: finding specific API capabilities, required parameters, or data models based on keywords. It also advises chaining results into 'get-endpoint'. While it lacks explicit when-not-to-use statements, the context of sibling tools implies alternatives.

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