From 98de525b9d6bec4be1f620c2326e5e4df0995d91 Mon Sep 17 00:00:00 2001 From: Will-hxw Date: Wed, 29 Apr 2026 09:12:20 +0800 Subject: [PATCH] fix(docs): sort tools by required args in tool reference Issue #1932: Tools within each category should be sorted with no-arg tools first, followed by tools with required args, then tools with only optional args. This matches the requested ordering in the issue. Updated both the TOC generation (generateToolsTOC) and the main reference generation (generateReference) to use the new sort order. Co-Authored-By: Claude Opus 4.7 --- scripts/generate-docs.ts | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index 4be8fcbd7..cf3f107db 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -141,8 +141,14 @@ function generateToolsTOC( const categoryName = labels[category]; toc += `- **${categoryName}** (${categoryTools.length} tools)\n`; - // Sort tools within category for TOC - categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name)); + // Sort tools within category for TOC: no-arg tools first, then with args + categoryTools.sort((a: Tool, b: Tool) => { + const aHasRequired = a.inputSchema?.required?.length ?? 0 > 0; + const bHasRequired = b.inputSchema?.required?.length ?? 0 > 0; + if (!aHasRequired && bHasRequired) return -1; + if (aHasRequired && !bHasRequired) return 1; + return a.name.localeCompare(b.name); + }); for (const tool of categoryTools) { const anchorLink = tool.name.toLowerCase(); toc += ` - [\`${tool.name}\`](docs/tool-reference.md#${anchorLink})\n`; @@ -361,8 +367,14 @@ async function generateReference( markdown += `> NOTE: ${categoryName} are not active by default. Use the '${flagName}' flag\n\n`; } - // Sort tools within category - categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name)); + // Sort tools within category: no-arg tools first, then tools with required args, then optional-arg tools + categoryTools.sort((a: Tool, b: Tool) => { + const aHasRequired = a.inputSchema?.required?.length ?? 0 > 0; + const bHasRequired = b.inputSchema?.required?.length ?? 0 > 0; + if (!aHasRequired && bHasRequired) return -1; + if (aHasRequired && !bHasRequired) return 1; + return a.name.localeCompare(b.name); + }); for (const tool of categoryTools) { markdown += `### \`${tool.name}\`\n\n`;