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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the response bundles a provenance/attribution footer, which is useful behavioral context, but says nothing about size limits, missing-slug errors, or truncation of long markdown.

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 pieces with zero waste; the core action and payload are front-loaded before the Args block. The example slug earns its place by disambiguating format.

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, return values need not be described, and the readOnly annotations cover safety; the description supplies the identification and sourcing of the input. Only the absence of any sibling routing keeps 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?

Schema coverage is 0%, so the description must carry the load, and it does: the single slug parameter is explained as coming verbatim from list_skills with a concrete example ('malta-income-tax'). That is meaningfully more than the bare string type 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 (a skill's full markdown) plus the secondary payload, a provenance/attribution footer. 'Full markdown' also implicitly separates it from get_skill_sections, though that sibling is never named.

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 rather than stated: the slug must come from list_skills, which hints at the discovery-then-fetch workflow. There is no explicit guidance on when to prefer get_skill over get_skill_sections or search_skills.

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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the structure of the parsed result but says nothing about behavior an agent could trip over: what happens with an unknown slug, whether sections are ordered, or whether content is truncated.

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 core capability is front-loaded in the first clause, with the return shape in parentheses and the argument note after. It is tight and free of filler, though the Args block largely duplicates what the schema already states.

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 one required parameter, existing output schema, and annotations covering safety, the description covers what the tool returns and how to identify the target skill. The missing piece is the routing decision against its four sibling 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 0%, so the description must carry the slug definition, and it does: it identifies it as a skill slug and supplies a concrete example ("malta-income-tax"). It stops short of saying where a valid slug comes from, which would have closed the loop with list_skills.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("Fetch a skill parsed into sections") and clarifies the output shape as heading + content + level. It distinguishes the tool implicitly from get_skill by emphasizing the section-parsed form, but never names the sibling it differs from, so the differentiation is left to inference.

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 none of the plausible alternatives (get_skill, list_skills, search_skills) are mentioned. An agent can infer that this is the section-structured read rather than the flat read, but the choice must be guessed.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: only published skills are returned, and each entry carries quality tier and verifier. It does not mention ordering or whether the list is truncated, which keeps it 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 short blocks — summary, Args, Returns — with no filler, and the core purpose is front-loaded in the first sentence. The Returns line partly duplicates the output schema, but it is one line and aids scanning.

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-filter read tool with an output schema already defined, the description covers purpose, filter formats, and the result keys an agent needs. Gaps are minor: no ordering, no indication of whether results are paginated despite the total count.

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 full burden, and it delivers format examples for both parameters (jurisdiction codes like "MT", "GB", "US-CA"; category like "international"). That is meaningfully beyond the bare string|null schema, though it does not say whether matching is exact or prefix-based.

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 ("List published skills") plus the payload fields it surfaces (quality tier and verifier). It does not, however, distinguish itself from the sibling search_skills or get_skill, so an agent must infer the boundary between listing and searching.

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 word "Optional" on both filters implies the default is an unfiltered listing of all published skills, which is a usable cue. But there is no explicit guidance on when to choose this over search_skills, nor any note about prerequisites or result limits.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses non-obvious behavior: truncation semantics, the fact that 'total'/'returned' are counts of returned matches rather than corpus-wide totals (because counting everything would require reading every skill), and that unreadable skills are skipped and enumerated so the caller can distinguish a partial from a complete answer. This is exactly the kind of operational context annotations cannot convey.

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 purpose is front-loaded in a single sentence, followed by well-organized Args and Returns blocks. The paragraph explaining the 'total' backwards-compatible alias is longer than necessary and discusses a field that is not even listed in the documented result envelope, costing some economy.

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 two-parameter search tool with an output schema already present, the definition supplies more than enough to call it correctly, including result-field meanings the output schema alone would not explain. The one real gap is the unspecified format of jurisdiction codes, which an agent cannot infer from either the schema or the text.

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 full burden, and it does: query is clarified with concrete example terms and jurisdiction is explained as an optional limiting filter. It stops short of 5 because no valid jurisdiction code format or examples are given, leaving ambiguity about what values are accepted.

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 — 'Search skills by keyword across their markdown content' — which is clearly distinguishable from the sibling get_skill (single fetch), list_skills (enumeration) and get_skill_sections (structural retrieval). It does not explicitly name those alternatives, which is the only thing keeping it from 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?

Usage is only implied: the keyword-search framing signals when this tool is appropriate versus the retrieval siblings, but there is no explicit 'use this when...' statement and no exclusion guidance. The jurisdiction parameter's filtering role is mentioned without saying when to supply it.

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 and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it narrows by jurisdiction, asks clarifying questions rather than guessing, and returns one of three status-keyed shapes including guardrails to obey. Missing only things like whether state persists across calls.

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 lead sentence and the 'first call' routing statement are front-loaded, and the Args/Returns blocks are scannable. Some docstring scaffolding ('Args:', 'Returns:') is boilerplate, but the return-shape enumeration earns its space.

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-optional-parameter entry-point tool, the description covers purpose, trigger, parameter meaning, and the three possible response statuses with their key fields. An agent has everything needed to call it and to interpret the outcome without additional context.

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 burden, and it does add real meaning with free-form intent examples ('taxes', 'VAT return', 'set up a company') and ISO-style jurisdiction codes ('MT', 'GB', 'US-CA'). However, it never says both parameters are optional or what happens when they are omitted, which is the key semantic the bare anyOf/null schema does not convey.

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 opens with a specific verb and resource ('Begin a guided session') and then spells out the concrete outputs (scoping questions, skill recommendations, plan). It distinguishes itself from siblings by explaining that it decides which skills to 'get_skill', so an agent can tell it apart from get_skill or list_skills 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?

It gives an explicit trigger ('Use this as the **first** call when a user asks for help with anything tax, accounting, or formation-related'), which is strong when-to-use guidance. It does not state when *not* to use it or name an alternative for non-domain requests, so it falls just 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.

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

Annotations mark it readOnlyHint=true and openWorldHint=false, and the description supports that without contradiction: the tool only constructs a URL and never contacts GitHub. Beyond the annotations it discloses the crucial out-of-band behavior — the user must review, sign in under their own account, and click Submit — plus the absence of server-side credentials and preserved attribution. That two-step, human-in-the-loop nature is exactly what an agent could not infer 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?

The lead sentence front-loads the key fact and the Args block is dense and scannable with no filler. The Returns block largely restates the existing output schema, which is the only real redundancy; trimming it to a one-line pointer would tighten the definition 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 five-parameter tool with an output schema and safety annotations, everything an agent needs is present: purpose, trigger conditions, per-parameter meaning, the non-posting behavior, and the required follow-up action of surfacing the URL to the user. Nothing material is left ambiguous.

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 full burden and does so: summary is required and accepts markdown, title is auto-generated when omitted, skill_slug adds the `skill-feedback` label when set, jurisdiction takes codes like "MT"/"US-CA", and rating is bounded 1-5 — a constraint absent from the schema. Every parameter gains meaning beyond its bare type.

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 opens with a precise verb and artifact: 'Build a pre-filled GitHub New Issue URL.' It immediately rules out the misreading that it posts to GitHub, which is the one confusion an agent could plausibly have. No sibling tool does anything similar, so no differentiation is needed.

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 explicit trigger conditions with concrete examples (bug reports, skill inaccuracies, missing jurisdictions, suggested improvements) and names a companion prompt (`skill-feedback`) for the guided case. It does not state when *not* to use it or contrast with any alternative, but the sibling set contains no competing feedback path, so the practical risk is low.

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