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

Annotations already cover read-only and idempotent behavior, and the description adds the non-obvious resolution order: the workspace's own copy first, falling back to platform-mcp-hub's. That fallback is real behavioral value the annotations do not convey. It still omits what happens when no entry is found.

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, and the fallback detail is packed into a short parenthetical. It is arguably too terse, but 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 simple two-param getter with safety already declared by annotations and no output schema, the key resolution behavior is covered. However, the completely undocumented parameters and the silence on not-found behavior leave meaningful 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 0% for both required parameters, so the description carries the full burden, yet it never explains what 'category' or 'id' are or how they combine to identify an entry. No syntax, format, or namespace hints are given.

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 fragment names the resource (one catalog entry) and the exact return payload (full JSON), which separates it from catalog_search's multi-result listing and save_entry's write. The verb lives only in the title, not the description, but the intent is unambiguous.

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 statement and no reference to sibling tools such as catalog_search for discovery versus this tool for a known entry. The only implied usage is fetching by category+id, which an agent must infer.

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 openWorldHint=false. The description adds substantive behavioral detail beyond them: substring case-insensitive matching across named fields, a `source` field indicating which set an entry came from, `total` counting every match, and `hits` being capped at `limit`.

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-loads the core action and packs matching, scope, and return-count details into two sentences without filler. The first sentence is long but each clause carries information; the scope phrasing has minor 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 search tool whose annotations already cover the safety profile and which has no output schema, the description covers matching semantics, scope, and result-count behavior. It leaves the category parameter and the structure of returned hits to inference, which are minor gaps at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the query parameter's matching semantics (substring, case-insensitive, across listed fields) and the limit parameter's cap on hits, but leaves the separate category parameter's filtering semantics undocumented.

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' and resource 'entries', enumerates the searchable fields (id, label, category, country, docs URL, API host), and clarifies scope (your workspace's entries and runtime-bundled entries). It does not explicitly distinguish itself from sibling catalog_get, 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?

The description gives context about what is searched—'your workspace's entries and, in your own workspace, the entries bundled with the runtime'—but provides no explicit when-to-use guidance, prerequisites, or alternative-tool routing (e.g., catalog_get for a single entry).

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 declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, and the description adds real behavioral detail beyond them: each failed check emits the exact OS-specific install command, and fix:true only builds when node, npm, lockfile and writability are all present (npm ci + tsc). This discloses the mutation's safety preconditions, though it does not say what state changes if fix is skipped or how output is shaped.

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 'Preflight:' followed by a dense enumeration, with the fix behavior and mode values trailing. It is efficient for the amount it covers, though the parenthetical lists and '...' abbreviations make it slightly telegraphic.

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 does the work of explaining returns (per-check install commands, mode values) and the fix mutation path. For a one-parameter diagnostic tool with annotations already covering safety, this is close to complete, missing only a clear statement of the return shape.

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?

One parameter at 0% schema coverage, so the description carries the burden and does so: it defines fix:true as building the checkout's TypeScript runtime under stated conditions. The 'mode: full | python_only | blocked' string is ambiguous as to whether it is input or output, which slightly muddies the single-parameter story.

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 diagnostic verb and enumerates exactly what is checked: workspace/checkout, Python gate deps, uv, node (>=20), npm, and the TypeScript runtime. It is unmistakably distinct from all siblings (save_entry, lint_entry, generate_server, etc.), none of which perform environment preflight.

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?

'Preflight' implies use before running the pipeline, and the description notes the checkout case 'when contributing', which gives implied context. However it never states when NOT to use it or points to any alternative sibling, leaving the agent to infer the trigger 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?

Annotations already cover the read-only/idempotent/open-world profile; the description adds real value beyond them by flagging that 'the draft is not saved', the two-step review-then-save workflow, and that source parsing uses 'same guards as ingest_openapi'. It does not describe failure modes or fetch behavior for remote URLs, keeping it shy 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?

Front-loaded with the purpose and dense but mostly waste-free across three sentences. The heavy parenthetical and multiple parenthetical asides make it slightly harder to scan than an ideal definition.

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 draft/transform tool with no output schema and no annotation-adjacent gaps, the description covers what gets produced, how to select operations, the limit default, and the required follow-up save step. Missing details are limited to the id and docs_url parameters, which are minor.

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 0% schema coverage, the description must carry the parameters, and it explains source (URL/file/text), operations (operationIds or 'METHOD /path'), filter, and limit (default 25). It leaves id and docs_url undocumented, so it compensates well but not completely.

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 (Draft) plus resource (a generic entry from an OpenAPI 3 / Swagger 2 description) and defines what a 'generic entry' contains via a parenthetical. It clearly positions itself against siblings by referencing ingest_openapi (same guards) and save_entry (the persistence step).

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?

Explains when to use it (draft from an OpenAPI/Swagger spec given as URL, file path, or text) and describes the follow-on flow ('review it, then save_entry with category generic'). It does not explicitly contrast against template_entry or state when-not to use it, so it falls short of full alternative 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?

Annotations already cover safety (readOnlyHint=false, idempotent, non-destructive). The description adds meaningful behavioral context beyond them: what files get written, where, and the refusal-on-lint-errors constraint. It stops short of detailing return values or failure modes in depth.

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 core action and structured into workspace vs. checkout cases. Dense but each clause carries information; only mildly verbose.

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, so the description must describe returns, and it does list generated artifacts and the test template. However, it omits return format specifics and any credentials/permission requirements, leaving gaps for a generation tool.

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 compensate. It partially does by embedding category and id in the path template servers/<category>/<id>/mcp.json, hinting at their role, but adds no format constraints or allowed values.

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 clear purpose (making a linted entry runnable by generating config files) and details the concrete outputs, which helps distinguish it from siblings like lint_entry or save_entry. The verb phrasing 'Make ... runnable' is slightly abstract but the enumerated artifacts clarify intent.

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 mentions 'Refuses entries with lint errors,' which implies a prerequisite but not an explicit workflow. It never states when to use this versus alternatives such as save_entry, lint_entry, or test_server, leaving usage 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial behavior beyond them: the 60-operation index cutoff, the 25 MB size limit, external $ref fetching, Redoc embedding extraction, HTML/AsyncAPI failure modes with the exact error tokens returned. This is unusually rich disclosure of edge-case 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?

Front-loaded with purpose and source formats, then return shape, then edge cases. It is dense and reads as a single sprawling paragraph, but nearly every clause conveys actionable behavior rather than 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?

Despite no output schema, the description fully characterizes the return value (servers, security, per-operation method/path/params with location/type/enum/default, request body keys, 200 response shape, paging, rate limits). Combined with the documented failure modes, an agent has everything needed to call and 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 0%, so the description carries the burden. It explains `filter` well (a path, tag or word, and when it becomes mandatory) and `source` extensively via the format list, but the `limit` parameter (default 200) is never mentioned, leaving one of three parameters undocumented.

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?

Opens with a specific verb+resource ('Summarise API documentation') and enumerates the exact source formats accepted (OpenAPI 3.x/Swagger 2, Postman, API Blueprint, RAML, WSDL, GraphQL, RSS/Atom). An agent can distinguish this immediately from siblings like read_docs or catalog_get.

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?

States concrete usage conditions: specs over 60 operations return a one-line index and require a second call with `filter`; over 25 MB yields too_large; HTML pages other than Redoc yield not_openapi; AsyncAPI is not servable. It does not name a sibling alternative (e.g. read_docs), so it stops short of full when/when-not 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?

Annotations cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), so the agent knows this is a safe, repeatable read. The description adds valuable context by enumerating what lint categories are inspected (auth, evidence, live_check/auth_audit, secrets) which is beyond what the annotations reveal. It does not say what the errors/warnings look like, but the enumeration of check domains is substantial added 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?

Single sentence, front-loaded with the verb and resource, then a parenthetical list of what is checked. Efficient and no wasted words, though the long comma-delimited list is dense and could be slightly clearer if structured differently.

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 description covers what lint checks and that it returns errors and warnings, which is the core of what an agent needs. With no output schema and 0% parameter description coverage, the description leaves the parameter semantics and output shape underspecified. For a simple two-parameter read tool, it is adequate but incomplete.

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% and the schema has no descriptions for the two required parameters (category, id). The description says 'one entry' but never clarifies how category and id relate to identifying that entry, nor does it explain valid category values. With 0% schema coverage, the description must compensate but does not.

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 (Run the catalog lint) on a specific resource (one entry) and enumerates exactly what is checked (vocabulary verbs, expressions, placeholders, auth, evidence, live_check/auth_audit, secrets). This clearly distinguishes it from siblings like doctor (broader health check) and draft_entry, and an agent can tell what it is for 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?

The scope ('one entry') and the list of checks imply this is a validation tool to run against a specific entry, but there is no explicit statement of when to use it versus doctor or save_entry, and no mention of exclusions or prerequisites. Usage is inferable but not stated.

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 declare readOnlyHint=false and openWorldHint=true; the description adds real behavioral context beyond them: it spawns the entry over stdio, hits the real platform, never calls write tools, validates results against the output schema, and record:true writes a live_check block into the entry. This explains why the operation is not read-only despite not calling write tools. Missing details on failure modes or runtime cost.

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?

Dense but front-loaded: the core procedure comes first, then the plan/record modifiers. The inline plan JSON earns its space by defining an otherwise opaque parameter, though the sentence structure is packed.

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, open-world verification tool with no output schema and no annotation depth on permissions, the description covers the procedure but omits meaning for half the parameters and any mention of failure/report behavior. Adequate but with clear 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 coverage is 0% across 6 parameters, so the description carries the full burden. It documents `plan` (with its args/config/ids/skip/no_page2 shape) and `record` well, but leaves category, id, lang, and egress completely unexplained in both schema and description.

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 (verify/run live) and resource (the entry/server), and spells out the exact procedure: start the entry over stdio, call every READ tool against the real platform, validate against the output schema. It does not explicitly differentiate itself from close siblings like test_server or try_tool, which keeps it out of 5 territory.

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 name and the procedural description, and one boundary is stated ('write tools are never called'). However there is no explicit guidance on when to choose this over test_server, try_tool, or doctor, leaving the agent to infer the correct sibling.

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 openWorld. The description adds crucial behavioral context beyond annotations: URL safety re-checking on every redirect, refusal of private/loopback/metadata addresses, and a prompt-injection warning treating content as evidence not instructions. This is valuable context not covered by 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?

Three dense sentences with no wasted words. Information is front-loaded with the core operation, then parameters, then the reader mode, then security constraints. The security note is somewhat abrupt but 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?

Given 4 parameters, no output schema, and rich annotations, the description covers the essential behavioral traits: pagination windowing, content type handling, JS rendering fallback, and URL safety. It could mention error handling or rate limits but is largely complete for an agent to call it 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 0%, so the description must compensate. It explains offset and max_chars as windowing controls and reader as a fetch mode for JS-rendered pages. The url parameter is self-evident. However, it doesn't clarify default values or units for offset/max_chars beyond what the schema implies.

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 (one API documentation page), specifies supported formats, and clarifies exactly what is returned (readable text, title, links). Clearly distinguished from siblings like catalog_get or ingest_openapi by its page-fetching purpose.

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 use reader: true (JS-rendered pages or 403 responses), which is a clear conditional usage guideline. However, it doesn't state when to prefer this tool over alternatives like catalog_get for documentation lookup.

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 annotations (idempotent, non-destructive, closed-world write), it discloses merge semantics ('existing fields are kept unless the entry replaces them') and three concrete refusal conditions, which is real behavioral context. It does not say what a refusal returns or whether missing directories are created, so it is strong but not exhaustive.

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 dense sentences with the write target front-loaded and no filler. The refusal list is compact and each clause carries information, though the parenthetical about checkout locations makes the second sentence slightly tangled.

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 and a mutation tool, the description covers location, merge behavior, validation failures, and the next step, which is most of what an agent needs. Remaining gaps are the response shape and whether parent paths are auto-created.

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. It adds meaningful constraints for category (must be known) and id (must agree with the entry), and pins one entry field (adapter cannot be null), but the structure of the nested 'entry' object is left entirely undocumented.

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 pair (write/update) and an exact resource template, catalog/<category>/<id>.json, plus the two possible workspaces. It is clearly distinguishable from read-side siblings like catalog_get, though it never names which sibling it replaces (e.g. draft_entry).

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 two contexts for use (your own directory vs. the platform-mcp checkout when contributing) and prescribes the follow-up step 'Run lint_entry next,' giving a clear workflow position. It stops short of any explicit when-not-to-use condition or a named alternative for drafting.

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 openWorldHint=false, so the safety profile is covered. The description adds useful context about what the returned payload contains (skeleton, example, live-verified example, schemas), which is value beyond the annotations, but it says nothing about whether a category must pre-exist or error behavior for unknown categories.

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 dense sentences with the default mode front-loaded before the category alternative; no filler sentences. Slightly clause-heavy, but every clause carries information 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?

With no output schema, the description usefully enumerates what the template returns in both modes, and the read-only, idempotent annotations cover the safety profile. It is nearly complete; only guidance on category validity and interaction with sibling tools 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 0%, so the description must carry the parameter. It does: the default value 'generic' is explained along with its meaning, and a category name is explained along with how it changes the returned content. That is solid semantic coverage for a single optional parameter, though no valid category values or failure mode for invalid categories are given.

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 the resource (a template for an entry) and specifies exactly what content is returned in each mode: skeleton, example, adapter contract for 'generic', and verb vocabulary plus input/output schemas for a category. It is clear what the tool produces, though it is not framed as a verb+object operation and never distinguishes itself from catalog-adjacent siblings like draft_entry or generate_server by name.

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 two modes are explained (default generic vs named category) and the contributing-to-a-shared-catalog intent is implied, which gives the agent some basis for choosing. But there is no explicit when-to-use/when-not-to-use guidance and no reference to the alternative tools that also produce or manage entries.

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, openWorldHint=false, and idempotentHint, but the description adds real value: 'No network calls' reinforces the closed-world profile, and 'A missing Python contract test is a failure, not a silent pass' discloses fail-closed semantics an agent could not infer from annotations. It stops short of describing the result shape or runtime/timeout 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?

Front-loads the core action and then lists the gates; the closing failure-semantics sentence is high-value. The middle sentence is dense with parenthetical detail but every clause carries information, so it earns its length.

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 no-output-schema test-runner, the description covers what is checked and the failure rule, which is most of what an agent needs. It omits the return format (structured report vs. pass/fail) and how long the smoke tests take, minor gaps against the overall thoroughness.

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% for both params, so the description must compensate. It does clarify that `id` is the platform id used in test filenames (tests/test_<id>_python.py, tests/<id>.typescript.test.mjs), but `category` is never explained and no format guidance is given for either. 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 ('Run the gates') and resource ('one generated entry'), then enumerates exactly which gates: lint, contract tests, and a stdio smoke of `platform-mcp-hub serve --entry` in both runtimes. This is distinguishable from siblings like lint_entry (a subset) and live_verify/try_tool 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?

The phrase 'for one generated entry' implies the tool is used after generation, giving some context, but there is no explicit statement of when to prefer this over lint_entry, live_verify, or try_tool, nor any when-not condition. Usage is implied rather than guided.

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 readOnly/idempotent/openWorld, but the description adds substantial beyond that: it describes what is shown (URL, query, body, non-secret headers, raw response structure summary + truncated text, mapped result or error), discloses the Accept: application/json header behavior, and reassures 'Never calls write tools.' This is rich context not present in 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?

Three sentences, front-loaded with purpose then workflow guidance and a diagnostic tip. Slightly dense but every clause earns its place; 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?

For a diagnostic read tool with no output schema, the description covers purpose, behavior, headers, and workflow placement well. It falls short only on parameter meaning (how to specify which tool and argument payload), which is the one gap an agent needs filled.

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% and all five parameters (category, id, verb, arguments, max_chars) lack any documentation in either the schema or the description. The description never mentions which parameters select the tool or how arguments/max_chars behave, so it fails to compensate for the coverage 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 specific verb (call ONE read tool of a saved entry through the runtime) and resource (a saved entry's read tool), and explicitly distinguishes scope with 'Never calls write tools.' An agent can differentiate this from siblings like live_verify and test_server.

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?

Names the explicit workflow position: 'Use it to fix result paths before live_verify.' It also gives a concrete diagnostic heuristic (an empty list usually means result.items is wrong or the platform changed format). When-to-use and the alternative (live_verify) are both stated.

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, idempotentHint=true, and openWorldHint=false, so safety and repeatability are covered. The description adds the useful fact that a workspace may be a local directory or a checkout and that it is changeable, but says nothing about the response shape or where the setting is stored.

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 compact sentence that front-loads the core concept. It is a sentence fragment and slightly elliptical ('how to change it' is ambiguous), but it wastes no words.

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-argument read-only tool with no output schema, the description does not say what the call actually returns (a path, a config block, instructions?) or how 'changing it' relates to this tool versus a separate setter. Adequate but with a clear gap for an agent deciding whether to call it.

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 semantics to document; the 4 baseline applies. Nothing in the description misleads 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?

The description explains the concept of a workspace ('where entries are saved... your own directory, or a platform-mcp checkout when contributing'), which clarifies the domain, but it never states the action the tool performs. An agent must infer 'show' from the title alone; the description reads like documentation of a concept rather than a statement of what this call returns.

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 guidance on when to invoke this versus siblings like doctor, catalog_search, or read_docs. The parenthetical about 'when contributing' hints at a scenario but doesn't tell the agent when it should call workspace at all.

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