My AI Guide

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the 2-3 tool arity and notes an extra return artifact (canonical /compare page URL), which is modest added context, but it says nothing about ordering, missing slugs, or error behavior.

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 with zero filler; the purpose and the arity constraint are front-loaded before the return-value note. Nothing could be removed 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?

With annotations covering the safety profile, a 100%-documented schema, and an output schema describing the return shape, the description only needs to convey purpose and scope, which it does. Minor gaps remain around how results are ordered or what happens with duplicate/unknown slugs.

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 'slugs' parameter is fully documented with minItems/maxItems and an example. The description merely restates the '2 to 3 tools' constraint already enforced by the schema, adding no new semantic 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 names a specific verb (Fetch) and resource (editorial records for tools, side by side) and pins the scope to 2-3 tools, which naturally separates it from single-tool siblings like get_tool. It does not explicitly name a sibling or state what it is not, so it falls just short of the top score.

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 phrase 'so you can compare them' implies the use case, but there is no explicit when-to-use/when-not guidance and no alternative tool is named (e.g. get_tool for a single tool, list_comparisons for pre-built comparisons). Usage 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds little beyond that – no mention of error behavior for invalid or non-existent ids, no rate-limit or pagination context.

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 compact sentences with the core action front-loaded and examples inline; nothing is padded. The trailing 'Returns id, title, text, and url' sentence is largely redundant given the output schema exists.

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 annotations covering safety and an output schema covering return values, the description only needs to convey the resource and id semantics, which it does. The remaining gap is the absence of sibling disambiguation among the many get_* tools.

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 'id' parameter is already documented with the same URL/path examples the description repeats. Baseline 3 applies since the schema does all the work and the description adds no extra format or validation 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 and resource ('Retrieve the full text of a myaiguide.co document by id') and clarifies the id format, so the action is unambiguous. It does not, however, differentiate itself from similar-looking siblings such as get_page or get_blog_post, which also appear to fetch site content.

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: the description signals this is a generic by-id fetch that accepts any site path or URL, which hints at broader applicability than the typed getters. There is no explicit statement of when to choose fetch over get_page/get_tool, nor any exclusion or precondition.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral detail is 'full body', which usefully implies complete content rather than an excerpt or summary.

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 short sentence with the verb, scope, and key all front-loaded. Every word earns its place and nothing is redundant.

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 one-parameter read tool with complete annotations and an output schema covering return values, the description is nearly sufficient. It is slightly thin on failure behavior (unknown slug) and on routing against get_page/list_blog, 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?

With 100% schema description coverage, the schema fully documents the single 'slug' parameter including an example format. The description merely repeats 'by slug' and adds no extra syntax or constraints, 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?

The description states a specific verb ('Fetch') and resource ('the full body of one blog post'), plus the lookup key ('by slug'). It is clearly distinct from the list_blog sibling, which is plural/listing, though it never names siblings or clarifies how it differs from get_page or search.

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 when-to-use guidance: nothing says whether this is preferred over search, list_blog, or get_page, nor what happens if the slug is unknown. Usage is only inferable from the singular 'one blog post by slug' phrasing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the payload includes the extended explanation and FAQ, which is modestly useful content scope, but it says nothing about missing/unknown slug behavior and the output schema already describes the return 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?

One sentence, front-loaded with verb and resource, with the returned content trailing. Every clause earns its place and there is no 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?

With an output schema present and 100% parameter coverage, the description need not explain return values; it correctly focuses on identity and scope. It is only slightly short of complete because it omits guidance on acquiring a slug and on how an unknown slug is handled.

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?

There is a single parameter with 100% schema description coverage, including an example slug value, so the schema carries the semantics. The description only restates that lookup is by slug and adds no format or edge-case 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?

The description names a specific verb (fetch) and resource (glossary term) and pins the lookup key (by slug), which cleanly separates it from the plural listing tool list_glossary. It stops short of explicitly naming or contrasting any sibling, 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 implied by 'by slug' – the agent understands this retrieves a single known term and that a slug is required. There is no explicit when-to-use, when-not-to-use, or pointer to how to obtain a slug (e.g. list_glossary or search) when it is unknown.

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 non-open-world, so the safety profile is covered. The description still adds value beyond them: it specifies the allowed domain scope ('Only paths on myaiguide.co are allowed') and the return nature ('readable text content', implying extraction rather than raw HTML). Both are useful and not derivable from annotations or schema.

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, front-loaded sentences that lead with verb+resource and examples. Slight redundancy: the myaiguide.co scope is effectively stated twice ('any page on myaiguide.co' and 'Only paths on myaiguide.co are allowed'), which trims a point but does not hurt readability.

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 read tool with a full output schema and annotations covering safety, an agent needs scope, format, and a sense of when to use it — all present. The only shortfall is the lack of explicit routing away from the more specific sibling getters, which is a minor omission rather than a blocking 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 100% and the 'path' parameter is already documented with format and an example, so the schema carries the semantics. The description repeats path examples but adds no new meaning beyond the domain restriction already counted under transparency. 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 ('Fetch the readable text content of any page on myaiguide.co by its path') and backs it with concrete path examples ('/about', '/disclosure', '/methodology', '/tools/claude'). The 'any public page' framing plus the editorial/trust-page examples implicitly positions it as the generic fallback distinct from the typed siblings (get_tool, get_blog_post), so an agent can place it 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?

It gives positive context (reads editorial, trust, and 'any other public page') and a hard constraint (only paths on myaiguide.co), which nudges the agent toward this tool for pages not covered elsewhere. However, it never names an alternative or states when NOT to use it — an agent with get_tool/get_blog_post/get_glossary_term available gets no explicit routing rule, so usage is only implied.

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, so the safety profile is fully covered structurally. The description's only added behavioral signal is 'full record', hinting the response is the complete entity rather than a summary, which is modest but genuine value.

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 sentence, front-loaded with the verb and resource, with zero filler. Nothing could be removed without losing 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?

For a single-parameter read lookup with a full output schema and rich annotations, the description covers the essentials; return values and safety are handled elsewhere. Minor gaps around slug-not-found behavior and repo-vs-plugin disambiguation keep it off a 5.

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 parameter already carries a concrete example ('safishamsi-graphify'), so the schema does the heavy lifting. The description adds no format, case-sensitivity, or namespace nuance beyond what the schema provides.

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 ('Fetch') plus resource ('full record for one repo/plugin'), and 'one' signals single-item retrieval as opposed to the list_repos sibling. It stops short of naming a sibling or fully disambiguating repo vs plugin as a lookup key, but an agent can tell what it does at a glance.

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 slug' implies the precondition (you must already have a slug), which is a reasonable usage cue. However, there is no explicit when-to-use-this-vs-list_repos-or-get_tool guidance and no statement of what happens when the slug is unknown.

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, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered. The description's payload inventory adds some context about what is exposed, but it is return-value content rather than behavioral traits (no auth needs, caching, freshness, or rate-limit notes). With annotations carrying the behavioral load, 3 is appropriate.

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 sentence with the verb front-loaded and a tight enumeration of returned fields; no filler, no restatement of the title, and every listed item is informative about what the caller receives.

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?

Because an output schema exists, the description is not obliged to document return values, and for a no-parameter, read-only tool the definition gives enough to call it correctly. The only real gap is the absence of usage guidance about when this context is relevant versus other retrieval tools.

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 the baseline of 4 applies. Nothing in the schema needs interpretation and the description correctly implies a no-argument call by never referencing any input.

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 concrete verb ('Returns') and then enumerates the exact resource contents: publisher identity, company registration, editorial contact, affiliate disclosure, canonical URL patterns, and machine-readable file locations. This is far more specific than the title and clearly distinct from data-retrieval siblings like get_page or get_repo. It stops short of naming a sibling or stating scope boundaries (e.g. 'this site only'), so it lands at 4 rather than 5.

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 when-to-use, when-not-to-use, or alternative named anywhere in the description. The content list lets an agent infer that this is the tool for site-level metadata, but no explicit routing guidance is provided and no siblings (e.g. list_site_sections, get_page) are referenced as alternatives.

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, non-destructive, and openWorldHint=false, so the safety profile is fully covered. The description adds payload-level context (the affiliate-safe /go redirect link, listed editorial fields) but says nothing about behavior beyond that, such as lookup failure handling or auth. 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?

One sentence, verb-first, zero filler. The field enumeration is longer than a bare statement but each item defines the returned record's scope, so nothing is wasted.

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 single-parameter read tool with full annotations and an output schema, the definition is essentially complete; listing return fields is redundant with the output schema but harmless. The only gap is no mention of the not-found / invalid-slug case.

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 'slug' parameter is already documented with an example in the schema. The description's phrase 'by slug' merely restates the schema, adding no format, normalization, or resolution semantics. Baseline 3 applies when the schema does the heavy lifting.

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 ('Fetch the full editorial record for one AI tool by slug') and enumerates the payload (rating, pricing, pros/cons, FAQ, /go link), which implicitly separates it from list_tools and get_tool_changelog. It never names a sibling explicitly, so it lands at clear-but-no-direct-differentiation rather than a 5.

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 when-to-use or when-not-to-use statement, no prerequisites, and no routing to alternatives. With siblings like get_tool_changelog, list_tools, and compare_tools in the same namespace, the agent gets no help deciding which to call.

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 fully covered by structured data. The description adds nothing beyond that—no mention of pagination behavior, sorting, or rate limits—so it earns a baseline 3 rather than higher.

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 single sentence that is perfectly front-loaded and wastes no words. It delivers the entire purpose without 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 lookup with an output schema and full annotation coverage, the description covers the essentials. However, it omits details like what constitutes a changelog entry (e.g., version history vs. edit history) and default sorting, which is adequate but not complete for an agent needing to interpret results.

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 both parameters are already documented in the schema. The description only re-iterates the slug scoping that the schema title implies, adding no new semantics beyond the default 20 limit note already in 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?

States a specific verb (Fetch) and resource (changelog entries) scoped to one tool by slug. An agent can immediately distinguish this from sibling list_tools or get_tool, which retrieve different resources.

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 implies usage through 'for one tool by slug' but does not explicitly state when to use this versus get_tool or compare_tools, nor does it mention any prerequisites or exclusions. Context is implied but not spelled out.

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=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds useful behavior the annotations do not: results are restricted to published posts (drafts excluded) and ordered newest first, which materially shapes what the agent receives.

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 sentence with zero filler; the scope constraint ('published') and ordering are front-loaded where they matter most.

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, and rich annotations plus 100% schema coverage carry the rest. The remaining agent-relevant facts—published-only scope and newest-first ordering—are stated in the description.

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% with only two params (limit default 20, category slug), both fully documented in the schema. The description adds no parameter syntax or format detail beyond that, 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+resource ('List published blog posts') with scope (guides and tutorials, published only) and ordering (newest first), which clearly separates it from get_blog_post and the generic list_* siblings. It stops short of naming any alternative tool, so it doesn't reach the top mark.

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 or when-not-to-use guidance and no mention of an alternative such as get_blog_post for a single post or search for querying. The only routing signal is implicit in calling it a 'list', so the agent must infer the use case from the verb alone.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds only the return shape (slugs and descriptions), which is useful but modest context beyond the 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?

A single front-loaded sentence with no filler. The verb and resource lead, and the payload detail trails. Every word earns its place.

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 and annotations cover the safety profile, so the description need not explain return values or side effects. For a simple zero-parameter list tool this is essentially complete, with only the sibling-routing gap remaining.

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 supply; the baseline for a no-parameter tool applies. Nothing in the description misrepresents the empty input 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 and resource ('List all tool categories') and adds scope detail ('with their slugs and descriptions'). However, it does not distinguish itself from the many sibling list_* tools (list_tools, list_blog, list_repos), so an agent must infer the boundary from the resource name alone.

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 when-to-use guidance, no stated relationship to list_tools or get_tool, and no exclusions. The description never explains when an agent should enumerate categories rather than fetch a specific tool or category-bearing resource.

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, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds the meaningful 'published' qualifier, implying drafts/unpublished comparisons are excluded, but says nothing about ordering, pagination, or result limits. Modest added value on top of 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?

A single front-loaded sentence with zero filler. Every word ('published', 'editorial', 'comparison pages') carries scope 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?

With no parameters, full annotation coverage of the safety profile, and an output schema that documents the return shape, the description covers what an agent needs. Only marginal omissions (ordering/result-size expectations) keep it from a 5.

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 nothing for the description to disambiguate; baseline 4 applies. The description does not need to explain arguments that do not exist.

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 published editorial comparison pages.' The resource ('comparison pages', scoped to published/editorial) is distinctive enough to separate it from the other list_* siblings, though it never names them. Clear but no explicit sibling differentiation.

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?

No when-to-use guidance is given. The presence of a sibling named compare_tools makes the absence of any routing note ('this enumerates comparison pages rather than comparing tools') a real gap. Usage is only inferable from the verb '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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that terms come with definitions (i.e., content is self-contained), but says nothing about ordering, pagination, or truncation behavior despite a 200-item default cap.

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 word carries meaning and the resource is named immediately after the verb.

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, and the one parameter is documented. However, for a list tool in a suite containing get_glossary_term, the absence of any retrieval-scope or alternative-tool guidance leaves a real 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 100% – the single 'limit' parameter is already documented in the schema with its default. The description adds no syntax, range, or behavioral detail beyond that, 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 ('List') and resource ('AI glossary terms') and adds scope detail ('plain-English ... with their definitions'). It is clear on its own, but it never distinguishes itself from the sibling get_glossary_term, which also concerns glossary terms.

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 guidance on when to use this versus get_glossary_term or the other list_* tools, and no mention of pagination or how to retrieve terms beyond the default limit of 200. The agent must infer usage from the name alone.

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, destructiveHint=false and openWorldHint=false, so safety is covered by structured data. The description adds genuinely new behavioral context: the result payload shape (install info, stars, descriptions) and that results are paginated, which matters for iteration planning.

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; the resource enumeration and payload summary come first, and the pagination note is a tight trailing fragment. Nothing needs to be cut.

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 and annotations covering the safety profile, the description only needs to frame what is listed and how results are chunked, both of which it does. The remaining gap is the absence of any disambiguation from list_tools and search.

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 both optional parameters (page, limit) carry full descriptions with defaults and bounds. The description's single word 'Paginated' corroborates but adds no syntax or format 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?

States a specific verb (List) and enumerates the resource types (published GitHub repos, Claude Code plugins, MCP servers, AI skills) plus what each entry carries (install info, stars, descriptions). It clearly distinguishes itself from content siblings like list_blog or list_glossary, but never distinguishes itself from the closest neighbor, list_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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as list_tools or search for a more targeted lookup. 'Paginated' weakly implies iteration behavior but says nothing about which tool to pick when an agent wants filtered or keyword-based results.

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, destructiveHint=false, and openWorldHint=false, so the safety and determinism profile is fully covered. The description adds only the static, bounded nature of the result set, and does not mention caching, updates, or pagination; with annotations carrying the load, this is adequate but thin.

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, front-loaded with the verb and scope. The long inline enumeration of sections is dense but earns its place by telling the agent what comes back; it could be trimmed without loss since an output schema exists.

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, idempotent list tool with an output schema and full annotation coverage, the description supplies the section list and per-section shape (path, title, description, URL). Complete enough to call correctly, with only explicit sibling routing 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?

There are zero parameters, so the baseline is 4. The description correctly implies a no-argument call by describing the full enumeration, and adds nothing that could mislead about inputs.

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) and resource (every public section of myaiguide.co), then enumerates the exact sections returned. An agent can distinguish this from siblings like list_tools or list_blog, which cover single section types, 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?

Usage is implied by the enumeration: this is the discovery/sitemap tool, while list_* siblings enumerate one section each. But the description never explicitly says when to prefer this over list_tools/list_blog or that it is the entry point for site structure, so the routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: only 'published' tools are returned, and results are paginated. It does not discuss auth, rate limits, or exact return shape, but the added constraints are meaningful.

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 compact sentences with zero waste. It front-loads the core action and then lists the main optional behaviors, making it easy for an agent to parse.

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 list endpoint with a fully described input schema, a present output schema, and rich read-only annotations, the description covers what it lists, how it can be filtered, sorted, and paginated. Nothing critical for correct invocation 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%, so the schema already documents all five parameters with defaults, enums, and examples. The description reinforces filtering by category and pricing model and sorting by rating or recency, but adds only mild semantic value (e.g., 'editor rating' vs. bare 'rating').

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 ('List') and resource ('published AI tools'), making the core purpose clear. It does not explicitly differentiate from siblings like 'search' or 'compare_tools', which could also surface tools, so it falls short of a 5.

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 implies when the tool is useful by describing optional filtering, sorting, and pagination, but gives no explicit guidance on when to use it instead of alternatives such as 'search' or 'get_tool'. No when-not or sibling routing is provided.

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, so the safety profile is covered. The description adds real behavioral context beyond that: a result cap of 10 and the fact that matches are returned with slugs and canonical URLs, which tells the agent the shape and breadth of what comes back.

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, no filler, with the search scope and the result cap both front-loaded. Every clause earns its place.

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 two-parameter, non-destructive search tool with an output schema present and safety fully covered by annotations, the description supplies what is needed: scope, result limit, and return shape. Not mentioning pagination or ranking order is a minor omission given the small fixed cap.

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 tools/repos/all enum and the 2-character minimum, so the schema does the heavy lifting and a baseline of 3 applies. The description's reference to the two catalogs loosely mirrors the 'type' enum but adds no syntax or default detail beyond what the schema already states.

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 ('full-text search') and both target resources (the AI tool directory and the repos/plugins catalog), which separates it from enumeration siblings like list_tools and list_repos and from the unrelated search_news. It does not explicitly name any sibling, so differentiation is inferred from the resource scope 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: an agent can infer this is the keyword-search entry point as opposed to browsing via list_* or fetching a single item via get_tool/get_repo. There is no explicit when-to-use, when-not-to-use, or fallback guidance, and no mention of how to handle zero results.

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 the full safety profile (readOnly, idempotent, non-destructive, not open-world), so the description only needs to add context. It contributes the 'newest first' ordering, but the entry-structure sentence (date, summary, link) largely duplicates the output schema, and there is no detail on result volume or coverage windows.

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 compact sentences with the purpose front-loaded and no filler. The final sentence about entry fields is mildly redundant given the output schema, but overall the structure is efficient.

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 a full schema, an output schema, and complete safety annotations, the description is sufficient to call the tool correctly. The main remaining gap is sibling differentiation for overlapping search/introspection tools, which is a routing concern rather than a calling one.

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 reinforces the no-argument default behavior but adds no syntax, format, or filtering detail beyond what the 'type', 'limit', and 'query' schema descriptions already provide.

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 ('Read the daily AI news roundups and weekly digests') and scopes the content to new models, releases, features and pricing. This clearly separates it from siblings like list_blog, search, and list_tools without needing the 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?

It gives a concrete calling condition ('Call it with no arguments to get the latest roundups'), which tells the agent the common case. It does not name alternatives (e.g. search or list_blog) or state when NOT to use this tool, so it stops short of full routing guidance.

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