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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial non-obvious behavior: "Never runs the code," the silent-failure policy ("Babel stays silent on anything it cannot prove" — dynamic code, hasattr guards, try/except ImportError), and the fact that those go into 'unchecked' rather than findings. That is exactly the kind of 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 core description is front-loaded and information-dense, with the key constraint (never runs code) early. The trailing keyword block is bulky and partially redundant with the opening line, which costs a point, though it aids retrieval.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description reproduces the full return shape ({ok, findings:[{line, col, severity, code, symbol, message, suggestion}], checked, unchecked, libraries}) and defines the semantics of 'ok' and 'warning' severity. An agent has everything needed to call and interpret this 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 carry the load, and it does: 'code' requires imports to be included, 'env' accepts an environment id, a project folder path, or omission for the default, and 'language' enumerates "python" (full checks) vs "typescript" (v1: named imports only). Each parameter's accepted values and limitations are explained.

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 (check) plus the precise resource (code against installed library APIs) and enumerates the failure classes it detects: unknown modules/attributes, unexpected kwargs, arg-count errors, deprecated calls. This clearly separates it from the docs_* and api_lookup siblings, which retrieve information rather than validate a snippet.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit temporal guidance: "Run it on code you wrote before showing it; fix errors, re-check." That is a clear when-to-use rule. It does not name a sibling alternative or state when-not to use it, so it falls short of a 5.

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 (readOnly, idempotent, closed-world), and the description adds genuinely new behavioral context: first-use indexing is local with no network but 'can take seconds', plus the failure semantics of found=false and the meaning of certain=false. This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the Args/Returns/Keywords layout is scannable, with the keyword line serving search recall. Slightly long and the first parenthetical overlaps with the Returns section, but every block earns its place given the tool's complexity.

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 supplies the return shape itself, including the params sub-object and the doc_truncated flag with a pointer to docs_read. Together with the documented parameters, the first-use indexing caveat, and the ambiguity caveat, an agent has everything needed to call and interpret 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?

Schema description coverage is 0%, so the description carries the full burden and does so for all three parameters: symbol as 'fully dotted path starting with the import name', env as 'environment id, project folder path, or omitted for the default environment', and library as 'optional library name to disambiguate'. Required vs optional is also implied by the defaults discussion.

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 ('Exact signature of an installed API') and immediately scopes it with parenthetical detail (signature, parameters, docs, installed version). Concrete example symbols ('pandas.DataFrame.merge', 'json.dumps', 'react.useState') make it trivially distinguishable from siblings like docs_search or docs_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Use it before calling any API you are not sure about') and routes follow-up work to a sibling ('Use docs_read(id) for the rest of a long doc'). It also notes the indexing precondition on first use. No explicit when-not-this-tool statement, so it stops short of a 5.

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 non-readOnly, idempotent, non-destructive, closed-world. The description adds real context beyond them: the per-language default-env rule, that re-registering is harmless and re-promotes the default, and that dependency indexing runs as a background job. It stops short of stating auth requirements or what gets mutated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and args are cleanly separated, but the bilingual duplication ('register project, registrar proyecto') and the trailing Keywords list repeat the same information in two languages, adding length without adding selection value.

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 mutation tool with no output schema, the description documents the return shape ({environment, dependency_job_id, dependencies, message}), the accepted inputs, and the default-env consequence. Only the relationship to sibling tools remains unaddressed.

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 carries the burden, and it does: 'path' is explained as an absolute path to a project folder, interpreter, or node_modules (with auto-detected venv/node_modules locations), and 'index_dependencies' is explained as indexing pyproject.toml/requirements*.txt in a background job. Both parameters get meaning beyond the bare 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 (register) and resource (project folder/venv/interpreter) plus the goal (so its packages can be checked). However, it never distinguishes itself from the sibling docs_index_folder, which sounds similarly scoped, so an agent must infer the boundary.

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?

Implies when to use it ('so its packages can be checked') and notes re-registration is harmless and re-sets the default. But it names no alternative and gives no explicit when-not guidance versus docs_index_folder or docs_libraries, leaving the sibling choice 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 cover readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description still adds value by disclosing the network dependency ('Reaches the internet (the public DevDocs catalogue)') and the return payload shape, which the annotations do not 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?

Front-loaded and well-sectioned with Args/Returns, but the trailing multilingual keyword block and the partial sentence fragment 'Reaches the internet (the public DevDocs catalogue)' before the Args section add noise that does not earn its place for an agent.

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, yet the description spells out the return shape ({results: [{slug, name, version, db_size_kb}], count, total, truncated}), so an agent knows exactly what it gets back before calling. Nothing material is missing for a two-param read-only listing 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 description coverage is 0%, so the description carries the full burden and does: query is 'filter by name or slug' with concrete examples, and limit documents both the default (10) and the max (50), neither of which appears 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+resource ('List downloadable offline docsets') and immediately names the sibling relationship ('Use before docs_install_docset'), letting an agent distinguish it from docs_search, docs_libraries, and docs_read without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it: 'Use before docs_install_docset to get the exact slug.' This names the downstream tool and the precondition, which is exactly the routing guidance an agent needs.

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 write/idempotent/non-destructive profile, and the description adds real behavior beyond them: accepted extensions (.md/.mdx/.rst/.txt), automatic skipping of dependency/VCS/build folders, and a hard cap of 2000 files. What it omits is what happens on re-index of an already-indexed path or how errors surface.

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 constraints (file types, skipped folders, 2000-file cap) are front-loaded in the first paragraph after the summary line. It is somewhat padded by duplicated multilingual keyword lines at the top and bottom, which repeat the same intent rather than adding 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 two-parameter indexing tool with no output schema, the description supplies inputs, indexing scope, limits, and the returned object shape ({id, name, status, entry_count, note, hint}). Nothing essential for a 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 0%, so the description carries the full burden and does: it states that path must be an absolute path to the folder and that name is a display/filter label defaulting to the folder name. Both parameters gain meaning the bare schema does not 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?

States a specific verb+resource (index a folder of Markdown docs) and explicitly ties it to the downstream consumers docs_search and docs_read, which separates it from those siblings. An agent can tell it builds a searchable index rather than performing a 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?

The phrase 'so docs_search and docs_read can use it' gives clear context for when this tool is needed, plus example sources (a project's docs/ folder, a cloned docs repo). No explicit when-not or exclusion guidance is offered, so it falls short of a 5.

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=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context the annotations lack: it reaches the internet, runs asynchronously in the background, and returns immediately rather than blocking.

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 opening sentence is front-loaded with the scope and the sync/async behavior, and the Args/Returns blocks are compact. The bilingual keyword lines restate content already in the first sentence, which is mild padding but may aid retrieval.

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 supplies the return shape {job_id, status, slug, message} and the async job-tracking workflow. An agent has everything needed to invoke it and know what to do next.

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% for the single 'slug' parameter, so the description must compensate. It does: the slug is defined as the exact identifier from docs_catalog with a concrete example ('python~3.13'), which is enough to call the tool correctly.

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: 'Download and index one offline docset in background.' The word 'offline' plus 'background' distinguishes it from siblings like docs_index_folder and docs_catalog 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?

Gives an explicit workflow: slug comes from docs_catalog, follow progress with docs_libraries (jobs), then search with docs_search. It names the prerequisite source and the follow-up tools, though it does not explicitly exclude docs_index_folder as an alternative.

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, but the description adds real behavioral context: auto-indexing of unlisted packages, the meaning of default_for when env is omitted, and pagination defaults. It does not cover auth requirements or rate limits, which is a minor gap for a read tool.

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 purpose, then scope, usage, args and returns in a clean structure. The bilingual keyword line is retrievability padding but is short and clearly separated, and the Returns block earns its space since no 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 no output schema and 0% param documentation in the schema, the description supplies both the argument semantics and a full return shape (libraries, environments, jobs with their fields). An agent has everything needed to call and interpret this 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 description coverage is 0%, so the description must compensate, and it largely does: it enumerates valid ecosystem values, explains env as an id or project path that limits results, and gives limit's default (15) and max (200) plus offset's paging role. Those are exactly the details absent from the bare 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 indexed libraries, exact versions and project environments') and enumerates the returned entity classes (libraries, environments, jobs), so an agent knows exactly what this tool surfaces. It does not explicitly contrast itself with docs_catalog, but the scope is unambiguous enough on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete use cases: 'Use it to find an env id, or to follow a docset install / dependency indexing job.' It also clarifies the fallback path — unlisted packages are auto-indexed when api_lookup or api_check_code need them — which steers the agent away from unnecessary calls. No explicit 'do not use for X' exclusion is given, so not a full 5.

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 safety is covered. The description adds genuinely useful behavioral context beyond that: the chunked-read model, the default and maximum chunk sizes, and how continuation works via next_offset. It does not mention any rate limits or failure modes for bad ids.

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 one-line purpose, then structures Args and Returns explicitly, which is easy to parse. The multilingual keyword tail ('leer documentacion, seguir leyendo...') is redundant for a model already reading the English description, but it is conventional for retrieval-style tools and costs little.

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 3-parameter, no-output-schema tool, the description supplies everything needed: purpose, id provenance, pagination mechanics, size limits, and even the exact return object keys ({found, qualname, library, text, offset, total_chars, has_more, next_offset}). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: id is 'passed back exactly', offset is a character offset to continue from using next_offset, and max_chars has a stated default of 4000 and a hard max of 20000. Every parameter is documented with semantics the bare schema lacks.

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 ('Read the full text of one doc entry by id') plus the delivery mode ('in chunks'), which cleanly separates it from docs_search and docs_catalog. It also defines what an 'entry' is (docset page section, markdown section, long docstring), removing ambiguity about the unit being read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete provenance for the required id ('Ids come from docs_search results and from api_lookup (field id)') and tells the agent how to continue reading via next_offset. It stops short of an explicit when-not rule (e.g. 'use docs_search first to find ids'), but the routing context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: indexed-scope limitation, ranking, a did_you_mean fallback, and 200-character truncation of signatures/summaries. It stops short of explaining scoring or pagination semantics.

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 purpose and routing advice, then cleanly sectioned into Args/Returns. Loses a point for duplicating keyword lists in both the opening parenthetical and the trailing 'Keywords:' line, which is redundant padding.

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 six parameters, 0% schema coverage and no output schema, the description compensates fully by documenting every argument and the exact return shape ({results, count, truncated, did_you_mean}), plus scope limits and next-step 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 description coverage is 0%, so the description carries the full burden and does: it explains each of the six parameters, including that camelCase/snake_case/dotted identifiers match by parts, gives concrete values for ecosystem and kind, and specifies limit defaults (8) and max (50).

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 ('Ranked full-text search over indexed APIs, offline docsets and markdown docs') and explicitly separates itself from siblings by naming api_lookup and docs_read as the follow-up steps once a result is chosen.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit selection condition ('Use it when you know roughly what you need but not the exact name') with concrete examples, names the alternatives to use afterwards (api_lookup on qualname, docs_read on section id), and states the boundary 'Only searches what is already indexed.'

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