mcptoon

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

Annotations already communicate the open-world/destructive nature, so the description only needs to add context; it does so by noting the withheld tool list and that arguments are validated first. There is no contradiction between the description and 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?

Three sentences, each earning its place: core action, usage context, and validation behavior. No filler or repetition of schema/annotation data.

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 an open-world dispatcher, the description covers how a name is found, what form it takes, how to obtain the arguments object, and the validation guarantee. The output schema covers return expectations, so nothing critical is missing.

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 schema already documents the name pattern and points to mcptoon_inspect for the arguments object. The description's 'validated first' is behavioral rather than semantic parameter detail.

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 a specific action—'Run any upstream tool'—and names the exact resource format ('namespaced name (server_tool)'). It also separates this execution tool from sibling discovery/introspection tools by pointing to how one arrives at a name via mcptoon_manifest.

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 gives a concrete when-to-use signal: under default compact exposure the tool list is withheld, so this is the route to run a tool discovered through mcptoon_manifest. It does not explicitly list when-not-to-use cases or name alternative tools, which keeps it a 4 rather than a 5.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds genuinely useful behavioral context the annotations do not: this is a diagnostic/introspection call that reveals configuration and load state, and that it is the correct first step in a missing-tool investigation. It does not discuss cost or failure modes, but the read-only nature makes those minor.

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, zero waste. The enumerated outputs come first, then the diagnostic guidance, so the agent gets the gist immediately. Every clause carries 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?

An output schema exists, so return values need no explanation, yet the description still names the salient fields. A parameterless, closed-world, read-only diagnostic tool is fully specified here; nothing an agent needs in order to invoke it correctly is missing.

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, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly implies the call takes no arguments, matching 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?

States a specific verb+resource ('Self-check of this gateway process') and enumerates exactly what it reports: version, config path, servers configured, tools indexed, uptime. This clearly distinguishes it from siblings like mcptoon_manifest and mcptoon_servers, which expose registry contents rather than process health.

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?

Gives an explicit trigger ('Read this first when a tool you expect is missing') and names the diagnostic distinction it resolves (empty config vs. server that failed to load). The condition for choosing this tool over any sibling is unambiguous.

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, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read-only; nothing runs' and adds the workflow sequencing, but adds little beyond what annotations already convey.

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 tight sentences that lead with the core action, then state the read-only behavior and the suggested usage context. There is zero filler or 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 read-only inspection tool with full schema coverage, annotations, and an output schema, the description covers purpose, safety, and when to call it. Nothing essential is missing.

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% for both parameters, including the namespaced tool name and server disambiguation. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 states a specific verb ('Show') and resource ('one upstream tool's full input schema'), and clarifies that it is read-only and executes nothing. This distinguishes it from mcptoon_call and other siblings despite not naming them explicitly.

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 explicitly says 'Use it after mcptoon_manifest names a tool,' giving a clear workflow context. The statement 'nothing runs' implies it is not for execution, but it does not name an alternative like mcptoon_call, so it stops short of a full when-not alternatives list.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so safety is covered. The description adds real behavioral context beyond that: the default response contains names only, and enabling descriptions costs tokens, letting the agent reason about output size.

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?

Three short sentences, front-loaded with what the tool returns, then the recommended usage, then the optional parameter. Every sentence carries information and nothing is padded.

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?

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description covers scope, defaults, and cost; only minor details (e.g., how grouping keys are structured) are left implicit.

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% and both parameters are already documented there, so the baseline is 3. The description largely restates the include_descriptions effect ('one-line summary per tool' / default false) and adds nothing about the server filter's matching semantics.

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?

States a specific verb and resource ('List the upstream tools this gateway currently exposes') plus the grouping scope ('grouped by server') and the default output shape (names only). It is clearly distinguishable from sibling tools like mcptoon_servers, which enumerates servers rather than exposed 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?

Explicitly tells the agent to read this compact view 'instead of pulling every full schema,' which is real when-to-use guidance, and it explains when to pass include_descriptions (one-line summaries) versus keeping the small default. It stops short of naming a specific alternative sibling tool or stating 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?

Beyond the readOnly and idempotent annotations, the description adds that ranking is 'Offline BM25 ranking, no LLM.' This tells the agent the algorithm is deterministic and fast, and that no external LLM call is involved. This is useful behavioral context that the annotations do not cover.

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 concise sentences. The first states the core function; the second gives the usage timing and the algorithm. No wasted words, and the most important info (purpose and when to call) is 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?

The tool has an output schema, so return values don't need explanation. The description covers what it does, when to call it, and the follow-up step (read SKILL.md). For a simple read-only resolution tool, this is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds extra guidance: 'More detail ranks better than a single keyword' for task, and for k it explains the default and when to increase it ('larger only when the top few look wrong'). These go beyond the schema descriptions, so a 4 is warranted.

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 action: 'Return the skills that best match a task description, best first.' It specifies the resource (skills) and the matching criterion, and distinguishes this from simply listing all skills (a likely sibling). The verb is specific and unambiguous.

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 a direct usage instruction: 'Call this with the user's request before acting.' It also implies the workflow by telling the agent to read the chosen skill's SKILL.md after. It doesn't explicitly name alternatives or state when not to use it, but the context 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it describes what the call returns (the full uncompressed text) and the dependency on a handle emitted by the compression step.

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, both front-loaded with purpose then trigger; every clause earns its place and nothing is repeated or padded.

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?

With an output schema present, return-value detail can be omitted, and the description covers the remaining essentials: what is retrieved, why it exists (compression round-trip), and when to invoke it. Nothing needed to call it correctly is missing.

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 single handle parameter is already documented in the schema's own description, including its format and where it comes from. The description adds no syntax or format detail beyond what the structured field provides, so the baseline 3 applies.

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?

States a specific verb and resource ('Get back the full, uncompressed text of a tool result mcptoon compressed') and ties it to the compression mechanism, which no sibling tool does. An agent can distinguish this from mcptoon_call or mcptoon_inspect without opening any schema.

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?

Gives a concrete trigger condition: 'When a result ends with a line naming a handle, call this if the summary lacks a detail you need.' This is clear when-to-use context, though it stops short of stating when not to call it or naming an alternative retrieval path.

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 cover safety (readOnly, idempotent, openWorld=false, non-destructive). The description adds genuine behavioral context beyond that: it discloses what state is examined (load status) and surfaces a diagnostic condition ('configured but published nothing') that an agent would not know to look for from annotations alone.

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 tight sentences with zero filler; the purpose is front-loaded and the usage sentence adds distinct value rather than restating the first.

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?

With an output schema present, return values need no explanation, and the description covers purpose, usage, and the optional narrowing parameter. Nothing an agent needs to call this correctly is missing.

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%, and the schema already documents the single optional 'server' parameter including alias resolution. The description only implies an all-by-default scope, adding nothing the schema does not already say, so the baseline of 3 applies.

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?

States a specific verb and resource ('report the MCP servers configured behind this gateway') and enumerates the reported fields (transport, tool count, load status). An agent can distinguish this from siblings like mcptoon_manifest and mcptoon_health without opening any schema.

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?

Gives clear usage context: 'see what is actually reachable before calling a tool' and spot servers that published nothing. No explicit when-not or named alternative sibling, but the diagnostic framing makes the use case unambiguous.

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 supply readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by clarifying 'offline and read-only' and explaining the alias-card behavior. No contradiction with annotations; the only minor gap is no detail about result ordering or size, but the output schema covers return structure.

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?

Three short, information-dense sentences with no filler. The purpose is front-loaded, and the follow-up tool reference and optional parameter hint each occupy their own meaningful sentence.

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 low-complexity, read-only catalog tool with one optional boolean parameter and a provided output schema, the description is complete. It covers what the tool returns, how to use it in the broader discovery flow, and its safety/offline characteristics.

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% and the include_aliases parameter is already well-documented in the schema. The description mostly restates the same meaning ('pass include_aliases to also see alias cards'), adding little beyond the schema baseline.

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?

States a specific verb ('List'), a clear resource ('the skills mcptoon indexes'), and the output shape (slug and one-line description). It also distinguishes itself from the sibling mcptoon_resolve_skills by framing itself as the discovery step before resolution.

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?

Explicitly tells the agent to read this once to learn available skills and then resolve the target with mcptoon_resolve_skills. It also gives the optional include_aliases usage condition, making the intended workflow unambiguous.

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 establish readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context beyond those: 'Report these numbers verbatim; never estimate them yourself.' This is a real instruction about how to handle output data that prevents a common agent failure mode.

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, each earning its place. The first front-loads the resource and the specific metrics; the second delivers the when-to-call guidance and the verbatim-handling instruction. Zero filler words.

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 zero-parameter, read-only reporting tool with an output schema and full annotation coverage, nothing essential is missing. The description explains what the report contains, when to invoke it, and how the values must be handled. Low complexity means low documentation burden, and this fully meets it.

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 baseline is 4. Schema coverage is provably complete at 100% since the schema is an empty object. The description's mention of the three reported metrics is output-related rather than parameter-related, but no compensation 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 names a specific resource (this gateway's savings) and enumerates the exact data points returned: tools compressed, tokens saved, and session call count. This verb+resource framing distinguishes it from siblings like mcptoon_health, mcptoon_manifest, and mcptoon_servers without needing to open their schemas.

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?

Gives an explicit trigger condition: 'Call this when you want to tell the user what mcptoon did.' This provides clear context for when the tool is appropriate. It stops short of a 5 because it doesn't explicitly name alternatives or state when not to use it, but the use case is unambiguous.

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