Kudosity

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description merely restates 'executes an API request', adding no behavioral context beyond what annotations provide, such as potential side effects or rate limits.

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

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

The description is a single sentence, concise and front-loaded. However, it could be more informative without sacrificing conciseness.

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?

Despite complex nested parameters and no output schema, the description is minimal. It does not explain return values, error handling, or the side effects of the destructive operation. The tool needs more context for safe use.

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 in detail. The description does not add any additional meaning or examples 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?

The description clearly states the verb 'executes' and the resource 'API request with a given HAR request object'. It is specific but does not differentiate from sibling tools like get-endpoint or list-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?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use, or any contextual hints. The schema includes a hint about using list-specs or search-endpoints for the title, but the description omits this.

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, establishing the tool as a safe read operation. The description adds value by specifying what details are returned (security schemes, servers), which goes beyond annotations. No contradictions noted.

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 compact sentence of 16 words, front-loading the verb and key information. No fluff or redundant details. 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 tool with 3 required params and no output schema, the description provides informative context about the return value (detailed info, security schemes, servers). While it could further detail the output structure, it sufficiently covers what the tool returns and is adequate for an information retrieval 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% with each parameter having a clear description (path example, title with cross-reference, method examples). The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline of 3.

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 'gets' and the resource 'detailed information about a specific API endpoint', and specifies included details ('security schemes and servers'). This distinguishes it from sibling tools like list-endpoints (which lists endpoints) and search-endpoints (which searches).

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 does not explicitly state when to use this tool versus alternatives. It implies it is for retrieving details of a specific endpoint, but lacks guidance on scenarios like needing full security details vs. listing endpoints. Absence of 'when not to use' or cross-tool references lowers the score.

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=true, so the description adds minimal behavioral context. It confirms the non-destructive nature and mentions output organization, but doesn't disclose pagination, rate limits, or other traits 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 a single, clear sentence that front-loads the primary purpose. Every word serves a function with no redundancies or unnecessary 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?

For a simple listing tool with one parameter, the description covers key aspects: what is listed (paths, methods, summaries) and how results can be used. Missing details like pagination or output format are acceptable given the tool's simplicity and no output schema.

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 description adds no extra meaning to the 'title' parameter beyond what the schema already provides (which includes references to sibling tools). No additional semantic value is added.

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, HTTP methods, and summaries organized by path, with a specific verb and distinct resource. It differentiates from siblings by noting results can be passed into 'get-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?

The description implies usage by mentioning direct input into 'get-endpoint', but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives like 'search-endpoints' or 'list-specs'. Parameter description references siblings but not in main guidelines.

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, so the description adds no additional behavioral context. It does not describe the output format, pagination, or any potential side effects. For a simple list tool without output schema, more detail about the return structure would improve transparency.

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 short but the second sentence is potentially misleading and not clearly necessary. It could be more concise by removing the second sentence or clarifying that the title field in the response is for subsequent tool usage.

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 simplicity (no parameters, no output schema), the description is mostly adequate but lacks details on what the output contains (e.g., spec names, titles). Sibling tools use titles, so specifying that the output includes titles would make it more complete.

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

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

There are no parameters, so the baseline is 4. The description does not need to add parameter meaning, but the second sentence about 'using the title' might imply a filtering parameter that doesn't exist, which is slightly confusing. Nonetheless, schema coverage is 100% by default.

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 available OpenAPI specs. This distinguishes it from sibling tools like list-endpoints (which lists endpoints within a spec) and search-endpoints (which searches). The extra sentence 'Use the title to select a spec.' is somewhat ambiguous since there are no parameters, but does not detract from the core purpose.

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 hints at using the title for selection, implying this tool is a precursor to other operations, but it does not explicitly state when to use this tool versus alternatives like list-endpoints or search-endpoints. No exclusions or context about when not to use it 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?

The description discloses behavioral traits beyond the readOnlyHint annotation: it specifies that the tool returns a per-operation routing plan with version, endpoint, auth, and example, and that it will ask clarifying questions if information is missing. This adds useful context about interaction and output format.

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 concise at three sentences. It is well-structured: first sentence states purpose, second describes output format, third gives behavioral instruction. Every sentence is essential and front-loaded.

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 and no output schema, the description adequately covers the tool's purpose, output, and interactive behavior. It provides enough context for an AI agent to understand its role and distinguish it from sibling tools, though no explicit differentiation is made.

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 no parameters, and schema description coverage is 100%. The description adds value by explaining what the tool does without needing parameters, which is appropriate for a routing decision tool. The baseline for zero parameters 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's purpose: to determine which Kudosity API version to use for each operation based on user intent and authentication. It uses a specific verb ('determine') and resource ('routing plan'), and it distinguishes from sibling tools that focus on executing requests or listing 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 provides context on when to use the tool: when the user wants to send SMS, configure webhooks, etc., and depending on auth method. It also instructs to ask clarifying questions if info is missing. However, it does not explicitly state when not to use it or alternatives, though the sibling tools are distinct.

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 context beyond the readOnlyHint annotation by specifying the 'deep search' scope and the ability to pass results to get-endpoint. It does not contradict annotations, and the readOnlyHint already indicates no destructive side effects.

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 at two sentences, front-loading the purpose and following with usage guidance. Every sentence 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 simple search tool with one parameter and no output schema, the description provides sufficient context: what is searched (paths, operations, parameters) and how results are used (fed into get-endpoint). No gaps remain.

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 100% schema coverage and a single parameter (pattern) already documented as case-insensitive, the description adds no additional meaning beyond what the schema provides. 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 that the tool performs a deep search through paths, operations, and parameters to discover API endpoints. It specifies the verb 'search' and the resource 'endpoints', and distinguishes from sibling tools like list-endpoints and get-endpoint by focusing on 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 explains when to use the tool (to find specific capabilities, parameters, or data models) and mentions that results can be passed to get-endpoint. However, it does not explicitly contrast with sibling tools or state when not to use it, which would strengthen guidance.

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