mcp

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

No annotations are provided, so the description carries the burden. It says 'Return the JSON-Schema input contract' which is a read-only operation. It does not disclose any behavioral traits like side effects or auth needs, but for a simple retrieval tool, the description is adequate.

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 front-loads the purpose. Every word is necessary, and there is no wasted text.

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 tool with one parameter and no output schema or annotations, the description is complete. It clearly explains the tool's functionality and input.

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 mentions 'by name', which clarifies that the parameter 'name' is the tool's name. With 0% schema description coverage, the description adds some meaning beyond the schema, but it is minimal.

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?

Description clearly states it returns the JSON-Schema input contract for a tool by name. The verb 'Return' and resource 'JSON-Schema input contract' are specific. It distinguishes from siblings: list_tools lists all tools, execute_tool runs a tool, and list_scopes lists scopes.

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: when you need the input schema of a specific tool. No explicit when-not or alternatives, but the sibling context makes it clear that this tool is for schema retrieval, not execution or listing.

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?

Since no annotations are provided, the description carries the full burden. It mentions that 'input is forwarded raw,' which hints at no transformation, but it fails to disclose error handling, required permissions, side effects, or the need for input to match the target tool's schema.

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 (two short sentences) and front-loads the purpose. However, it sacrifices informativeness for brevity, leaving gaps in usage and behavioral 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?

Given the tool's role as a generic executor and the lack of output schema, the description should at minimum explain that the input must be valid for the target tool. It fails to do so, making it incomplete for safe and correct agent usage.

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 0% description coverage, so the description must compensate. It adds that 'name' is a tool name and 'input' is forwarded raw, but it does not clarify the format or constraints of 'input' (e.g., it must be a valid argument for the named tool). This is insufficient for an agent to correctly construct the input.

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 action: 'Invoke a tool by name.' It uses a specific verb ('Invoke') and resource ('a tool'), and it is easily distinguished from siblings like describe_tool_input (which describes input) and list_tools (which lists 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?

No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned. The description simply states what the tool does without context for decision-making.

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?

With no annotations provided, the description carries the full burden. It accurately discloses that the tool returns a list of allowed MCP scopes, which is a read-only operation with no side effects. 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 a single, clear sentence with no extraneous words. It is appropriately front-loaded and 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 no output schema, the description explains the return value as 'the list of allowed MCP scopes,' which is sufficient for a simple list operation. No further details (e.g., format) are necessary for this minimal 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?

The tool has zero parameters, so schema description coverage is 100%. Per rubric, 0 params yields a baseline of 4. The description adds no parameter info, but none is needed.

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 returns a list of allowed MCP scopes, using a specific verb ('Return') and resource ('list of allowed MCP scopes'). It is distinct from sibling tools like list_tools (which lists tools, not scopes) and describe_tool_input (which describes parameters).

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 no explicit guidance on when to use this tool or when not to. Since there are no parameters or alternatives, usage is implied (get scopes), but no context is given.

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?

No annotations are provided, so the description bears full responsibility. It implies a read-only discovery tool but does not explicitly confirm safety or disclose any side effects. Lacks details on permissions, rate limits, or data returned.

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, front-loaded with purpose and usage. Every sentence adds value. No redundancy or fluff.

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 output schema and no annotations, the description explains basic usage and output type ('domain index' or filtered list). However, it lacks details on output structure, parameter effects, and prerequisites, leaving some gaps for a complex tool with 3 parameters.

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 0% description coverage. The description adds that parameters allow filtering ('filter with domain/search_terms/scope') but does not explain meaning or allowed values beyond what the schema (e.g., scope enum) provides. Adequate but not rich.

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: 'Discover Apideck tools.' It specifies behavior: no args returns domain index, and filtering by domain, search_terms, scope. It is easily distinguishable from siblings like describe_tool_input, execute_tool, and list_scopes.

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 guidance on when to use the tool and how to call it: 'Call with no args for domain index; filter with domain/search_terms/scope.' It does not explicitly state when not to use, but the context is sufficient.

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