mcp

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, aligning with the description's read-only return behavior. The description adds no extra behavioral context (e.g., performance, error conditions), so it meets baseline but doesn't exceed annotation coverage.

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 communicates the exact purpose with zero redundancy. It is appropriately sized for a simple introspection 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?

Given the tool's simplicity (1 param, annotations safe, no output schema), the description fully explains what it returns and how to identify the target tool (via the param schema). It is complete enough for an agent to select and invoke correctly, though it could explicitly mention list_tools in the description itself.

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 'name' parameter well-described including an example and reference to list_tools. The description itself adds no parameter-level detail 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 clearly states the verb ('Return') and the resource ('JSON-Schema input contract') scoped by tool name, which distinguishes it from siblings like execute_tool (which executes) and list_tools (which lists tools). It precisely communicates what the tool does.

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: the tool retrieves a schema by name, and the schema's description references list_tools for exact names. However, the description itself does not explicitly state when to use this vs. alternatives (e.g., before execution) or provide exclusions, leaving the agent to infer 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 indicate non-read-only, non-idempotent, non-destructive, open-world behavior. The description adds one behavioral detail: 'input is forwarded raw to the tool handler,' which clarifies that arguments are passed verbatim. However, it does not disclose that invoking arbitrary tools may have side effects or that return values vary—important context beyond 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?

Two concise sentences, front-loaded with the action, and no unnecessary words. Every phrase earns its place: the first states the purpose, the second clarifies argument 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 the tool's generic dispatch nature and absence of an output schema, the description should mention return behavior or error outcomes, but it does not. The rich schema and annotations compensate partially, but the lack of return-value disclosure leaves a notable gap for an agent invoking unknown tools.

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 input parameter already explaining 'forwarded verbatim to the target tool' and referencing describe_tool_input. The description's 'input is forwarded raw' adds little beyond the schema, so it meets the baseline but does not elevate it.

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: 'Invoke a tool by name.' This specific verb+resource distinguishes it from sibling tools like list_tools (listing tools) and describe_tool_input (describing inputs). It is unambiguous and immediately identifies the tool as the execution dispatcher.

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—it is the tool to execute other tools—but provides no explicit 'when to use' or 'when not to use' guidance, nor does it name alternatives. The sibling context makes the role clear, but the description itself lacks explicit direction on selecting this tool over others.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds 'allowed', which slightly clarifies scope constraints but does not disclose additional behavioral 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?

A single, clear sentence that immediately states the tool's purpose. No wasted words 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 simple, parameterless, read-only tool with strong annotations and no output schema, the description adequately explains the return (a list) and the resource (MCP scopes). The simplicity of the tool does not require further elaboration.

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 trivially covers all parameter semantics. Baseline 4 is appropriate for parameterless tools.

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 ('Return') and names the resource ('the list of allowed MCP scopes'), clearly distinguishing it from sibling tools like list_tools or execute_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?

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states the action without contextual usage cues.

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, so the safety profile is established. The description adds behavioral detail about filtering and the domain-index behavior, but does not disclose return format, pagination, or rate limits. For a read-only discovery tool, this is adequate but 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 two short sentences that front-load the purpose ('Discover Apideck tools') and immediately provide usage instructions. It is concise, free of fluff, and every sentence 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?

The tool is simple, with strong annotations and fully described parameters. The description covers invocation patterns clearly. However, given no output schema, it omits return-value details such as what the 'domain index' looks like or whether tool names/descriptions are returned. It is still sufficient for an agent to use 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?

The input schema provides 100% coverage with descriptive text for scope, domain, and search_terms. The description merely mentions the filter parameters by name without adding new semantic detail beyond what the schema already provides. It meets the baseline but does not augment it.

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 'Discover Apideck tools', a specific verb-resource pair that clearly states the tool's purpose. It differentiates from sibling tools like execute_tool and describe_tool_input by positioning this as the discovery entry point. The mention of 'domain index' and filtering further clarifies its scope.

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 call patterns: 'Call with no args for domain index' and 'filter with domain/search_terms/scope'. It provides clear context on how to use the tool, though it does not explicitly state when not to use it or name alternatives like describe_tool_input for detailed schema inspection. This is clear context without exclusions.

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