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

No annotations are supplied, so the description carries the burden; it discloses two non-obvious behaviors: settings are session-scoped and override env/file, and the raw token must never be echoed back. It omits error behavior, whether settings persist across restarts, and what clearing secrets actually does.

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 the action, then precedence, then the triggering scenario, then the security rule. No filler; every sentence adds a distinct fact.

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 description covers purpose, precedence, and when to invoke, and an output schema exists so return values need no explanation. However, for a six-parameter mutation tool with zero schema coverage and no annotations, the untouched parameters (notably clear_secrets and timeout) are a real completeness gap.

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 0% and the schema only provides titles, so the description must compensate. It names only host/token (via 'pastes host/token'), leaving cookie, timeout, base_url, and clear_secrets entirely unexplained in both schema and description.

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: 'Set runtime connection settings for this MCP session', and adds the scope constraint '(overrides env/file)'. It is clearly distinct from the read-only sibling yapi_get_config, though it does not name that sibling 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?

Gives explicit when-not guidance ('Prefer env vars or `.yapi-mcp.json` for durable config') and an explicit when-to condition ('Use this when the user pastes host/token in chat'). The agent can decide between this tool and out-of-band configuration without inference.

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, the description carries the full burden, and it does disclose the important default behavior (index only, method/path/title) and that include_details adds normalized bodies capped by limit. It omits auth/config expectations for url, token, base_url and project_id, and does not confirm this is a read-only operation. Useful behavioral context, but incomplete for a 6-parameter call.

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 short sentences, front-loaded with the purpose and then the default-versus-opt-in behavior. Minimal waste, though the 'agent understanding / client scaffolding' phrasing is slightly loose.

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 presence of an output schema means return values need not be explained, and the default/detail modes are covered. But for a 6-parameter tool with zero schema descriptions and no annotations, leaving four parameters and all credential setup undocumented is a significant completeness gap.

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 0%, so the description must compensate, and it only explains include_details and limit (including their interaction). Four parameters — url, token, base_url, project_id — are given no meaning anywhere, leaving the agent to guess at connection and targeting 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: export a project's API catalog, with the stated purpose of agent understanding / client scaffolding. This is distinguishable from siblings like yapi_list_interfaces and yapi_get_interface, which return individual or filtered items rather than a bulk catalog export. It stops short of explicitly naming those siblings as alternatives.

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?

Implied usage is clear (build a catalog for an agent or scaffold a client), and it explains the default index-only mode versus opting into details. However, there is no explicit guidance on when to prefer this over yapi_list_interfaces or yapi_get_interface, and no stated prerequisites such as needing project_id or credentials.

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 carries the full behavioral burden. It does earn credit for disclosing that secret values are excluded from the response, a real trait not derivable from the empty schema, but it says nothing about what happens when no configuration exists, whether defaults are merged in, or what the effective settings include.

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 front-loaded sentence with no filler. Every qualifier ("non-secret", "currently in effect") carries meaning.

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 no parameters and an output schema present, the description needn't explain return values, and it correctly stays brief. The remaining gap is state-related context, such as whether unconfigured or default values appear, which an agent would want before deciding to call 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 takes zero parameters, so there is no parameter meaning for the description to add. Baseline 4 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?

"Show non-secret connection settings currently in effect" gives a specific verb (Show) and a specific resource (connection settings), with the scope qualifiers "non-secret" and "currently in effect" narrowing it. It is clearly a read of the effective config rather than a mutation, but it never names the sibling yapi_configure as the counterpart, so the differentiation is inferred rather than stated.

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 only implied: "currently in effect" suggests inspecting live state rather than stored settings, which hints at when to reach for this over yapi_configure. There is no explicit when-to-use, no prerequisite, and no statement that this is the diagnostic step before/after configuring.

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 supplied, so the description carries the disclosure burden; 'Get' implies a read, but that is inference rather than a stated guarantee. It says nothing about the token parameter being an auth credential, permission requirements, error behavior for a bad id/URL, or what happens when both url and interface_id are supplied. A partial credit of 3 reflects the useful 'full definition for codegen' scope statement.

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 lines: purpose first, then input acquisition, then a concrete URL example that earns its space. 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?

The output schema exists, so return-value detail is not needed, and the core retrieval purpose is covered. However, with no annotations and zero schema coverage, the definition leaves auth (token), base_url, and the url-vs-interface_id precedence unexplained — gaps an agent would hit on first invocation.

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 0% across four parameters, so the description must compensate. It adds genuine meaning for interface_id (source: yapi_list_interfaces) and url (detail URL shape with an example), but token and base_url are left entirely undefined, and the precedence between url and interface_id is unstated.

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 one interface's full JSON request/response definition') plus the intended use case (client codegen), which separates it from the list-oriented sibling yapi_list_interfaces. It stops short of an explicit contrast statement, but the singular 'one interface' vs. a listing tool is clear enough to select on.

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 concrete entry paths: take interface_id from yapi_list_interfaces, or paste a detail URL in the shown format. That is real routing guidance for how to obtain inputs. It does not mention when to prefer yapi_parse_url or yapi_get_project instead, nor any 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?

No annotations are supplied, so the description carries full behavioral burden, yet it only implies a read. It says nothing about authentication/token requirements, how url vs base_url vs project_id resolution works, or what happens when optional parameters are omitted.

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?

One short, front-loaded sentence with zero filler; the parenthetical field list is compact and informative.

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 not be described, but a four-parameter tool with entirely undocumented parameters and no annotations leaves an agent unsure how to target a project or authenticate. The description is underspecified for this level of schema complexity.

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?

All four parameters (url, token, base_url, project_id) have 0% schema description coverage and are all optional with null defaults, which raises a real question of how the target project is identified. The description lists output fields instead of explaining any parameter's role, so it adds no meaning beyond the bare 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 uses a specific verb+resource ('Get YApi project metadata') and even enumerates returned fields (name, basepath, desc), which separates it from retrieval siblings like yapi_get_config and yapi_get_interface. It does not, however, explicitly contrast itself with those siblings.

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?

There is no statement of when to use this versus yapi_get_config, yapi_get_project's natural alternative, nor any prerequisites. The only implicit cue is that it returns project-level rather than interface-level data.

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 supplied, the description carries the full behavioral burden; it does state that this is a read/list operation and discloses the credential resolution order (env / config / token arg), which is valuable. It says nothing about pagination, result limits, permission requirements, or error behavior on a bad URL or project id.

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 lines with the core action front-loaded and the two invocation modes grouped together. No filler, though the trailing 'Credentials via env / config / token arg' is terse to the point of being cryptic about precedence.

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 not be explained, and the auth/invocation story is covered. For a 7-parameter tool with zero schema description coverage, though, the undefined filter parameters and absent pagination/scope notes leave meaningful gaps.

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 0% across 7 parameters, so the description must compensate and largely does not. It only explains url, project_id, base_url, and token; path, method, and keyword are never described, leaving the filter semantics ('optional filters' is vague) undocumented anywhere.

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 gives a specific verb and resource: 'List interfaces under a YApi project', plus the parenthetical '(from list_menu)' tying it to a project-listing step. It does not distinguish itself from siblings like yapi_get_interface or yapi_export_catalog, and 'optional filters' is left unnamed.

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 does explain two invocation paths (a browser URL vs project_id + base_url) and how credentials are supplied, which is real usage guidance. However, there is no when-to-use vs when-not guidance relative to siblings such as yapi_get_project or yapi_get_interface, so routing still requires inference.

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 supplied, so the description carries the full burden, and it never states that this is a pure local string transformation with no network call or side effects. It also says nothing about failure behavior for malformed or non-YApi URLs, or whether the input is normalized; an output schema exists but only covers success shape, not error semantics.

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 lines, front-loaded with what is produced, followed by a concrete example — nothing extraneous. The example is slightly weakened by its trailing slash and missing interface segment, which can confuse an agent about what form to submit.

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 one-parameter parsing utility with an output schema, the description covers the essential contract: input kind, output fields, and an example. The remaining gap — what happens on invalid input and which URL shapes are tolerated — is minor but real for a tool with zero parameter documentation.

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 0% — the single 'url' property carries only a type — so the description must compensate. It does so partially by naming it a YApi page URL and giving one example, but the example ('https://yapi.example.com/project/123/interface/api/') shows only one URL shape, is truncated without an interface id despite advertising interface_id as an output, and gives no guidance on accepted URL variants.

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 ('Parse') on a specific resource ('YApi page URL') and enumerates exactly what the result decomposes into: base_url, project_id, and optional interface_id. No sibling tool (configure, get_config, get_project, list_interfaces, get_interface, export_catalog) does URL decomposition, so the function is 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?

There is no explicit when-to-use statement, no when-not-to-use, and no mention of siblings such as yapi_configure even though the parsed base_url/project_id would presumably feed those tools. Usage is only implied by the name and by the fact that the outputs match other tools' inputs.

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