yapi_export_catalog

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.