Apideck MCP

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

Annotations cover key behavioral traits: readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds context about its role in preparing for 'execute_tool', which is useful beyond annotations. However, it doesn't disclose additional behaviors like rate limits or error handling, so it adds some value but not rich behavioral details.

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 and front-loaded: two sentences that efficiently convey purpose and usage without waste. Every sentence earns its place by providing essential information, making it well-structured and appropriately sized.

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 low complexity (1 parameter, no output schema) and rich annotations, the description is mostly complete. It explains the tool's purpose and when to use it, but could benefit from mentioning what the output looks like (e.g., schema details) since there's no output schema. However, it adequately covers the context for a simple metadata 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 the parameter 'tool_names' fully documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides, such as format examples or constraints. Given the high schema coverage, the 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 the tool's purpose: 'Get the input schema for one or more tools.' It specifies the verb ('Get') and resource ('input schema'), but does not explicitly differentiate from siblings like 'list_tools' (which likely lists tool names rather than schemas). This makes it clear but not fully sibling-distinctive.

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 guidance: 'It is a good idea to call this tool first to understand how to successfully call execute_tool.' This directly advises when to use it (before 'execute_tool') and implies an alternative relationship, though it doesn't explicitly mention other siblings like 'list_scopes'.

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 provide rich behavioral hints (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), but the description adds valuable context beyond these. It explains the recommendation to call describe_tool_input first for schema understanding, which is practical guidance not captured in annotations. No contradiction with annotations exists.

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 perfectly concise: two sentences that each earn their place. The first sentence states the core purpose, and the second provides crucial usage guidance. No wasted words, and information is front-loaded appropriately.

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 (executing arbitrary tools with potential destruction), annotations cover safety aspects well, and the description adds practical usage guidance. However, there's no output schema, and the description doesn't explain return values or error handling, leaving some gaps for a tool with destructive potential.

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 both parameters (tool_name and input) well-documented in the schema. The description mentions 'tool by name' and 'input parameters' but doesn't add meaningful semantic details beyond what the schema already provides. Baseline 3 is appropriate when schema coverage is complete.

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: 'Execute a tool by name with the provided input parameters.' This is a specific verb+resource combination that distinguishes it from siblings like describe_tool_input (which describes inputs) and list_tools (which lists available tools). However, it doesn't explicitly differentiate from all siblings (e.g., list_scopes), so it's not a perfect 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 provides explicit usage guidance: 'If executing a given tool for the first time, it is recommended to call describe_tool_input first to understand the expected input schema.' This gives clear when-to-use advice (for first-time execution) and names a specific alternative tool (describe_tool_input) for preparation.

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 key behavioral hints (read-only, non-destructive, idempotent, closed-world). The description adds value by explaining what scopes are and their functional purpose (grouping tools, search terms), which helps the agent understand the output's utility beyond just listing items. No contradiction with annotations exists.

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 in the first sentence, followed by two concise sentences that add necessary context without redundancy. Every sentence earns its place by clarifying what scopes are and how they're used, making it appropriately sized and well-structured.

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 (0 parameters, no output schema) and rich annotations, the description is complete enough for an agent to understand its purpose and usage. It explains what scopes are and their role in tool filtering, though it could slightly enhance completeness by mentioning the relationship to sibling tools like 'list_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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately doesn't discuss parameters, as none exist, and instead focuses on the tool's output context, which is efficient and adds 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 the tool's purpose: 'List the scopes available on this server.' It specifies the verb ('List') and resource ('scopes'), and provides additional context about what scopes are ('categories that group related tools together'). However, it doesn't explicitly differentiate this tool from its sibling 'list_tools' beyond mentioning scopes vs. tools.

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 context by explaining that scopes 'can be used as search terms when filtering the list of tools,' suggesting this tool helps with tool discovery. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'list_tools' or 'describe_tool_input,' nor does it mention any prerequisites or exclusions.

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 read-only, non-destructive, and idempotent behavior, but the description adds value by specifying that filtering matches against 'tool name, description, and scopes' and uses logical OR for multiple terms. This provides operational context beyond the annotations, though it doesn't cover aspects like rate limits or auth needs, which are not contradicted.

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 core purpose and followed by optional filtering details. Every word earns its place without redundancy, making it efficient and well-structured for quick comprehension.

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 low complexity (one optional parameter), rich annotations, and no output schema, the description is reasonably complete. It covers purpose, filtering behavior, and match criteria, but lacks details on return format or pagination, which could be useful. However, for a simple listing tool, it provides adequate context without being exhaustive.

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% description coverage, fully documenting the 'search_terms' parameter. The description adds minimal semantics by mentioning 'filter by search terms' and what fields are matched, but this largely repeats schema details. With high schema coverage, the baseline is 3, as the description doesn't significantly enhance parameter understanding 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 'List' and resource 'available tools', specifying the action and target. It distinguishes from sibling tools like 'describe_tool_input' (details about a specific tool) and 'execute_tool' (runs a tool) by focusing on listing with optional filtering, making the purpose specific and differentiated.

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 clear context for usage: 'Optionally filter by search terms' implies it's for browsing or searching tools, with no explicit exclusions or alternatives mentioned. It doesn't specify when to use this vs. 'list_scopes' (which lists scopes rather than tools), but the context is sufficient for basic guidance without being misleading.

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