AIGC Radar MCP

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing a five-minute cached snapshot, the returned fields (source URL, fetch time), README language preservation, the SHA-guarded pagination contract, and an explicit prompt-injection warning to treat README text as untrusted data. That last item is genuinely operationally important and absent from structured fields.

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?

Front-loaded with what is returned, then routing, then pagination, then the safety note — a logical order with no filler. It is dense and slightly long, but nearly every sentence carries a distinct operational 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?

With no output schema, the description carries the burden and does so: it enumerates returned fields, the cache window, README language handling, and the pagination continuation path. An agent has everything needed to call and consume the result correctly.

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 75%, and the description supplies the missing relational meaning: readme.next_offset should be passed as readme_offset and readme.sha as readme_sha to continue the same version, and max_chars is implied by 'if more text is needed'. It doesn't restate bounds/defaults, which the schema already covers.

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 (Read) and resource (one public GitHub project's metadata and README Markdown), and even names the content facets (code blocks, links) and language behavior. An agent can distinguish it from search_github_projects without opening either 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?

Explicitly names where full_name comes from (search_github_ai_projects/search_github_projects or user-supplied owner/repo), lists the task conditions that justify a call (installation, configuration, deployment, feature verification, closer comparison), and states when not to call it (optional; don't fetch every search result) plus the no-prior-search case.

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 disclosure burden. It usefully signals that the payload is public metadata containing authors (array) and arxiv_id, but says nothing about error behavior for an unknown id, rate limits, or the response's remaining shape.

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 tight sentences, front-loaded with the purpose before the workflow guidance and payload note. No filler, though the third sentence drifts into presentation advice that is only marginally part of the tool's contract.

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 lookup with no output schema and no annotations, the description covers purpose, prerequisite workflow, and key payload fields, which is enough for correct invocation. It could say more about failure modes for an invalid or stale id, but 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% and the single parameter is documented as the id returned by a search or ranking tool, so the schema already does the work. The description only reinforces this ('by id') without adding format or validation detail, which matches the baseline 3 for high-coverage schemas.

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 ('Fetch'), a scoped resource ('public metadata for one indexed AIGC_NEWS document by id'), and distinguishes this single-item lookup from the search tools that produce the id. An agent can tell it apart from search_papers and get_top_items 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?

It states the trigger condition plainly ('Call this after search_papers or get_top_items when the user needs details for a specific item'), naming the upstream alternatives and the situation that selects this tool. It does not state any when-not case, so it falls just short of fully prescriptive routing.

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, so the description carries the burden. It discloses that it's a discovery/list tool with no required inputs and that it's a prerequisite only in the taxonomy-unknown case, which is useful. But it does not describe the return shape beyond 'categories and subcategory counts' or any caching/latency behavior; adequate but not rich.

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 tightly scoped sentences, front-loaded with what the tool does and immediately followed by the call-ordering rule and the prohibition. Zero filler.

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 parameterless discovery tool with no output schema, the description covers purpose, call ordering, and anti-patterns well. It could briefly note the return shape (names + counts) more explicitly, but nothing an agent needs 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 per the rubric the baseline is 4. The description correctly explains that no filtering inputs are needed since the whole taxonomy is returned.

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), resource (public AIGC_NEWS GitHub AI project categories), and adds subcategory counts. An agent can immediately tell what it returns without opening a 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?

Explicitly says to call it first only when the taxonomy is unclear, then route to search_github_ai_projects, and forbids using direct GitHub/web search just to discover categories. This is textbook when/when-not guidance.

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 behavioral burden. It usefully clarifies that results are authoritative official rankings rather than exploratory search results, but it does not disclose read-only status, pagination/limit behavior, return shape, or any access constraints.

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 front-loaded with the core purpose and then gives routing guidance. It is slightly repetitive in listing query phrasings such as ranking/leaderboard/top-N/chart/hot list, but the emphatic guidance is relevant for tool selection.

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 four parameters, low schema coverage, no annotations, and no output schema. The description is complete enough for tool selection and routing, but it leaves parameter details and return-value expectations underexplained, which matters given the structured-field 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 low at 25%, so the description should compensate. It names source, period, optional snapshot date, and top-N sizing, but it does not explain the enum meanings, limit range/default, or date interaction beyond what the schema already shows.

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 and resource ('Return the authoritative AIGC_NEWS ranking board') and scopes it to source, period, and optional date. It clearly distinguishes this tool from search tools, which is exactly what an agent needs to select it.

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 when to call this tool vs search alternatives: rankings, leaderboards, top-N lists, charts, hot lists, and 榜单 queries should use this tool, while search with scope='today' is for exploratory discovery. The exclusions and alternatives are stated directly.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed-world), so the lower bar applies. Beyond them, the description adds genuinely useful behavioral facts: results are license-reviewed, every set permits commercial use and redistribution, and the license notice must be retained with copied icons. It does not mention rate limits or caching, but the licensing/pinning context is substantive.

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?

Front-loaded with the verb and lookup key, then the payload list, then the licensing obligation, then the parameter tip. Three sentences and no filler. Slightly dense in the payload enumeration, but every clause carries information an agent needs.

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?

There is no output schema, so the description correctly compensates by listing the returned fields, and there is no pagination or auth concern to document for a read-only, idempotent lookup. The only shortfall is that the language parameter's effect on the returned prompt is left implicit, so an agent must infer it from the schema enum.

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 carry the parameter burden, and it does for two of three: 'id' is defined as a search result id and include_source is given a concrete semantic (false = metadata only). The language parameter is only obliquely referenced via 'Chinese/English integration prompt' and never stated as a selectable zh/en output-language switch, leaving that one gap.

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 precise verb (Retrieve) and resource (reviewed SVG icon) and pins the lookup key ('by its search result id'), which cleanly separates it from the sibling list-style tool search_ui_icons. It also enumerates the returned payload (svg source, SHA-256 hash, revision, author, license, prompt), so an agent knows exactly what comes back before opening the 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?

'by its search result id' establishes the precondition that this tool follows a search step, which is the key routing signal. It also gives an explicit mode switch ('Set include_source=false for metadata only'). It never names search_ui_icons directly or states when not to use this tool, so it stops short of full when/when-not guidance.

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 the safe read-only/idempotent profile, and the description layers on non-obvious behavior: omitted_files requiring per-file retrieval, next_offset/file_offset pagination with concatenation, license_notice_files, and the include_source=false metadata-only mode. These are real operational traits not derivable from structured fields.

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?

Front-loaded with purpose and usage before mechanics, and every sentence carries actionable content about retrieval behavior. It is dense and runs long, but nothing is filler; minor tightening of the pagination sentences would help.

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 output schema, the description fully carries the return-value burden: source files, SHA-256 hashes, pinned upstream revision, dependencies, author, license, and bilingual integration prompts. It also covers truncation and pagination edge cases, leaving no gap an agent would need to guess at.

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 only 40%, so the description must compensate, and it does for three of five params: file ('exact name'), file_offset ('repeat with file_offset until null and concatenate'), and include_source ('metadata only'). The id param's provenance is implied via the reference to search_ui_templates, but language ('zh'/'en' for the integration prompt) is never explained despite being the only enum.

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 ('Retrieve a curated UI template') plus the keying mechanism ('by its search result id'), which distinguishes it immediately from the sibling search_ui_templates. An agent can tell what this returns without opening the 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?

Explicitly names the triggering situations ('relevant new page, replacement, substantial redesign, or reusable component') and the sequencing rule ('call this before implementation rather than stopping at the search summary'), which routes the agent away from the search tool's terminal state. This is the when-to-use guidance most definitions lack.

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 behavioral burden. It discloses the source coverage, which is genuinely useful, but says nothing about result ordering, relevance behavior, pagination semantics, or what happens with an unmatched query — all of which the agent must infer from a read-only search pattern.

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 with zero filler: scope first, routing second. The reader learns the answer to "what does it cover" and "when should I pick this" in the first pass.

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 4-param read-only search with a fully documented schema and no output schema or annotations, the description covers purpose and routing adequately. Minor gaps remain around result behavior and the undocumented 'x' source value, but nothing an agent needs 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?

Schema description coverage is 100%, so q, page, limit and source are all self-documented; baseline is 3. The description's source list roughly mirrors the enum but omits the 'x' value, so it adds no syntax or filtering detail beyond the 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?

Specific verb (Search) plus resource (indexed AIGC_NEWS records) and an enumerated scope (arXiv, GitHub, news, Product Hunt, Hacker News). It also names the sibling tools it is *not* (search_papers, search_github_projects), so an agent can discriminate 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?

Explicit when-to-use ("explicit cross-source or indexed news/feed searches") plus explicit alternatives with their own selecting conditions (scholarly papers -> search_papers; GitHub discovery -> search_github_projects/search_github_ai_projects). Nothing is left to 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 does well: it discloses the ≥500-star floor, the bounded read-only fallback labeled github_api_fallback, the data_source 'aigcnews.cn' field, citation expectations, and a one-search-per-requirement rule. It stops short of describing return shape or pagination behavior across the 'page' parameter.

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?

Front-loaded and information-dense, but it is a single sprawling paragraph cramming routing rules, tool-ordering policy, ranking exclusions, adoption workflow, and citation rules together with little structural separation. Several clauses (host-tool fallback, star verification) repeat or restate each other and could be trimmed.

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 complex 10-parameter tool with no annotations and no output schema, the description adequately covers routing, preconditions, result provenance, and post-call behavior. It leaves some parameter guidance and the exact result/pagination model implicit, which is the main residual 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?

Coverage is only 40% across 10 parameters, and the description compensates for almost none of the gaps: it explains only that 'optional intent... only tunes relevance.' Parameters like q, page, limit, scope, category, and subcategory get no added meaning beyond their bare schema titles, leaving half the surface undocumented. The one genuinely useful clarification (intent is non-authoritative) does not offset that.

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 ('search of AIGC_NEWS's curated library of public GitHub AI projects') and immediately scopes it as not the user's favorites. Explicitly distinguishes itself from siblings: search_papers for scholarly output, search_github_projects for non-AI software, get_top_items for rankings.

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 exhaustive when-to-use triggers ('find, search, recommend, compare, or reuse'), when-not rules ('Skip narrow work... even when AI terms appear'), ordering constraints (call only this tool first, paper search in a later turn), and named alternatives for adjacent cases. Nothing is left to 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 behavioral burden and does so richly: it discloses a bounded read-only GitHub Search fallback labeled github_api_fallback, a 500-star quality floor for local and fallback results, the data_source value (aigcnews.cn), a citation requirement, and a caution against architecture-changing adoption without user choice. It also states that repositories are opened only when metadata cannot confirm a requested feature.

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 long but front-loaded: purpose first, then when-to-use/skip rules, then behavioral constraints. It is logically ordered and every sentence largely earns its place, though the density is high and some passages could be tightened without losing 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?

For a tool with no annotations, no output schema, and six parameters, the description provides extensive routing, fallback, quality-floor, citation, and adoption guidance. It covers enough for an agent to invoke the tool correctly and interpret its role; remaining gaps around pagination and exact return shape are minor for a search endpoint.

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 67%, with the schema already documenting q, lang, sort, and language in detail. The description adds meaningful semantic guidance for q (translate non-English intent into a concise GitHub query keeping product names and requested features), but it does not add meaning for page, limit, or beyond-schema behavior for sort/language. A baseline 3 is appropriate given moderate coverage and limited param-specific elaboration.

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 (search) and resource (public non-AI GitHub repositories and open-source software), and distinguishes itself from siblings search_github_ai_projects and search_papers. Also explicitly rules out the user's favorites, so an agent can route correctly without opening another 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?

Provides explicit when-to-use triggers (find, search, recommend, compare, reuse; also before implementing a major non-AI module), when-to-skip exclusions (copy/styling, renames, localized bugs, tests/logging/types, field tweaks, simple CRUD, single function/component/endpoint), and alternatives for AI artifacts and scholarly deliverables. Adds call-cadence rules (at most one initial search per unchanged requirement, no batching with WebSearch/WebFetch/Bash) and fallback conditions.

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 burden, and it does so well: it discloses the no-parallel-tools constraint, the web-tool fallback condition, per-item fields (authors array, arxiv_id), a search budget of about five calls, and a broadened-query retry limit of twice. It does not describe pagination behavior beyond the schema, which keeps it just short of 5.

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 content is valuable but densely packed into long run-on sentences, and the actionable instruction (issue this call in your first message) is buried mid-paragraph rather than front-loaded. The budget and citation rules at the end are useful but would benefit from separation.

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?

Covers query construction, tool routing, result-item fields, citation requirements, fallback behavior, and turn-ending expectations, which is complete for a 3-parameter search tool. It lacks any mention of pagination or result ordering, but with the schema documenting page and limit, this is only a minor omission.

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 baseline is 3. The description adds one piece of guidance beyond the schema, instructing the agent to rewrite academic intent into 1-3 established technical terms, which aligns with the q parameter but does not add syntax or format 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?

States a specific verb+resource (search for arXiv papers) and explicitly distinguishes itself from search_github_ai_projects by defining academic intent versus engineering artifacts. An agent can route between the two siblings without opening either 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?

Explicit when-to-use list (find, search, recommend, compare, reuse papers) plus a named alternative with its own trigger condition (engineering artifacts go to search_github_ai_projects). It also specifies sequencing: call search_papers alone in the first message, supplementary project searches only in later turns.

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-open-world, so safety is covered. The description adds substantive non-annotation context: the curated, license-audited, redistributable nature of the sets, the pinned upstream revisions, and the immutability of returned svg_url values. It does not describe result caps or pagination behavior, keeping it just short of a 5.

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, front-loaded with the what and constrained how, ending with the follow-up call routing. Dense but each sentence carries distinct information; the provider list is long yet earns its place by clarifying scope.

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?

No output schema exists, and the description compensates by naming the returned fields (icon ids, styles, aliases, immutable svg_url). With 6 parameters at 33% coverage, some gaps remain around limit/q semantics, but for a filtered search tool the description is close to 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 coverage is only 33%, so the description must compensate. It does add real meaning for set, style, and category by enumerating concrete style values (outline, filled, solid, regular) and noting that queries may be Chinese, English, or mixed, but it says nothing about q, limit, or language behavior beyond the enum. Partial compensation only.

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 (Search) over a precisely characterized resource (reviewed, commercially usable SVG icon sets), naming the actual providers (Tabler, Lucide, etc.) and the scoping constraint (pinned to audited upstream revisions). It is clearly distinguishable from the sibling get_ui_icon, which retrieves a single icon's source.

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 explains how to scope a search (by set, style, or category) and explicitly routes the agent to the sibling get_ui_icon for the verbatim SVG source, warning against redrawing or approximating. It lacks an explicit 'when not to use' or a statement of when a broad unfiltered query is appropriate, but the workflow context is clear.

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/closed-world, and the description adds genuinely new behavior: empty exact matches automatically relax to the strongest matching terms or an explicit category, and results are licensed upstream references with live previews. It does not cover pagination or rate/limit behavior, so it stops short of a 5.

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?

Purpose and the proactive-use trigger are front-loaded, and the hand-off to get_ui_template closes the paragraph usefully. It is dense and slightly repetitive (the redesign/restyle idea and the styling-attribute list overlap), so a trim would help, but no sentence is pure filler.

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 6-parameter search tool with no output schema and no parameter descriptions, the description supplies query semantics, filtering dimensions, return nature (references plus previews) and the downstream workflow. The main remaining gap is result-count/pagination behavior around limit, which an agent might need to call it optimally.

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 carries the load and mostly does: q is described as a Chinese/English/mixed natural-language brief with a concrete example, and kind, category (purpose facets like dashboard/authentication/navigation) and framework (HTML/Tailwind, React, Vue/Nuxt, CSS) are all given meaning. Only limit and the language parameter are left unexplained, which keeps it from a 5.

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 (find/search) plus the concrete resource set: UI components, pages, layout blocks, themes, shaders, animated backgrounds and text effects. It also names the sibling it hands off to (get_ui_template) for source retrieval, so an agent can distinguish it from search_ui_icons and the other search_* 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 states when to invoke (before creating, redesigning or restyling frontend, even unprompted) and enumerates the change types in scope (colors, spacing, typography, borders, radii, shadows, visual states, responsive presentation). It also gives the when-next rule: for new or reusable UI, follow a result with get_ui_template instead of inventing an approximation.

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 does disclose real behavior: the call is a persistent write that feeds a reuse-rate metric returned in the response, and it is idempotent-by-convention ('at most once per project per decision'). It does not state what happens on a repeat call, whether an existing receipt is overwritten, or any auth/permission requirement, which keeps it short of a 5 for an unannotated mutation.

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?

Purpose is front-loaded in sentence one, followed by trigger, decision cases, exclusions, and side effect in a logical order. The enumeration of the three decision values partly duplicates the schema enum, which costs a little density, but every sentence still carries actionable 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?

For a 5-parameter write tool with no annotations and no output schema, the description covers what it does, when to call it, when not to, the decision vocabulary, and what the response contains (the stored receipt plus the reuse-rate metric). It stops short of describing failure/duplicate-call behavior and permission needs.

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 every parameter (including the two enums) is already documented, so the schema does the heavy lifting and baseline is 3. The description restates the decision enum meanings and the query's purpose rather than adding format, constraint, or edge-case guidance beyond the 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 first sentence gives a specific verb and resource ('record the outcome of a project reuse decision as an adoption receipt'), and the second ties it to the exact sibling tools it follows (search_github_ai_projects/search_github_projects). An agent can distinguish this write-a-receipt tool from the read-only search siblings 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?

It states the trigger explicitly ('call this once after any search result leads to a concrete decision'), enumerates the qualifying decision cases, and gives clear exclusions ('do not call for projects that were merely listed, mentioned, or compared without a decision'). It also caps frequency ('at most once per project per decision'), leaving nothing to inference.

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