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

Beyond the readOnly/idempotent annotations, the description reveals critical runtime behavior: concurrency control (1-5), per-article failure isolation, token budget distribution, language override semantics, and partial-failure reporting. It even notes that the language parameter has no effect on certain domains. This substantially exceeds annotation coverage.

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 organized into clear sections (Args, Returns, Examples, Note) and front-loads the core purpose. It is slightly verbose with the Args list repeating some schema details, but every sentence adds operational value. Examples are helpful but could be trimmed.

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

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

For a complex batch tool with 6 params and an output schema, the description covers all aspects an agent needs: input constraints, parameter interactions, return shape, error handling, and usage examples. It complements the output schema without duplicating field-level return details.

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?

While the schema documents all six parameters (100% coverage), the description adds meaningful semantics: how maxTokens is split evenly, that concurrency limits parallel requests, how language overrides URL locale with no effect on certain domains, and what compact mode means. It clarifies behavior that the schema alone 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 clearly states the verb 'Retrieve' and resource 'multiple Jamf documentation articles in a single request', distinguishing it from the single-article sibling by highlighting batching and parallelism. The title and opening sentence unambiguously identify this as the bulk version of get_article.

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 concrete use cases ('comparing articles, gathering information from multiple pages, or bulk research') and includes examples. It does not explicitly name alternatives or exclusion conditions, but the batch context strongly implies when this tool is preferred over single-article fetches.

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 description thoroughly discloses behavior beyond the readOnly/idempotent annotations: how token limits apply to every reply, truncation logic, what happens when a section is not found (including the exact error message), and how the tool resolves conflicting address inputs. It also notes the quirk that most learn.jamf.com topics have no headings and are treated as sub-topics. This is rich, non-obvious behavior that far exceeds annotation coverage.

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

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

The description is long but well-organized into purpose, args, returns, examples, errors, and a detailed note. Every section adds necessary information for correct invocation. The intro is front-loaded with the core purpose, and technical details are logically grouped. There is no redundant filler; the density is justified by the tool's complexity (10 parameters, multiple hosts, and nuanced behaviors).

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 the tool's complexity, the description is remarkably complete. It covers all parameters, error cases, output formats (including a full JSON schema in the Returns section), token handling, and edge cases like missing sections or precedence of address inputs. It even explains the behavior for different document hosts. Nothing an agent needs to call this tool 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?

While the input schema covers 100% of parameters, the description adds significant semantic detail: the exact interplay between url and mapId/contentId, language override behavior for different host types, and the meaning of maxTokens in the context of truncation and summaryOnly. It explains that outputMode and responseFormat affect the output shape, and gives examples of valid parameter values. This goes well beyond the schema's field descriptions.

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 opening sentence states exactly what the tool does: 'Retrieve the full content of a specific Jamf documentation article.' It further explains that it fetches and parses an article into a clean format, and clarifies the supported hosts. This clearly distinguishes it from sibling tools like search or batch get, which serve different purposes.

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 provides explicit guidance on when to use URL vs. mapId + contentId, explains precedence when both are passed, and details when to use summaryOnly or section for long articles. It also gives concrete examples of valid calls. While it doesn't explicitly say 'use batch for multiple articles', the single-article scope is unambiguous and the examples reinforce the correct usage.

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, yet the description adds substantial operational detail: how pagination splits by top-level entry, that page assignment depends on maxTokens, that changing maxTokens mid-page breaks paging, the single truncated page behavior, the page-100 cap, and the exact error strings for bad product IDs and missing versions. This is well beyond the safety profile the annotations provide.

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-loading is good and the Note carries the highest-value content, but two full blocks are redundant: the Args list restates every schema property description verbatim, and the Returns section reproduces an entire JSON response shape that the output schema already defines. Roughly half the text duplicates structured data, diluting an otherwise well-organized payload.

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 an 8-parameter, paginated tool with a rich output schema, the description covers everything an agent needs: axis selection, the mutual-exclusion constraint, paging stability rules, truncation signaling, structuredContent continuation fields, and the mapId/contentId pairing for article fetches. Return values are where they belong, in the output schema, and the Note supplies the cross-call knowledge the schema cannot.

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 baseline is 3, but the description contributes genuine semantics the schema does not: 'Exactly one of product and publication is required' (the schema marks neither as required, so this constraint is only available here), the meaning of publication as a bundle family for non-product docs, and outputMode='compact' as a flat list without nested children rather than the schema's generic 'brief output'.

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 ('Get the table of contents for Jamf documentation') and immediately scopes it: 'Browse the navigation structure of either a Jamf product or any single Jamf publication.' It goes further than any sibling by explaining that release notes, technical papers, courses and guides live on the publication axis, not the product axis, so an agent can select correctly 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?

Gives clear context: 'Use this to discover what topics are available before searching or retrieving specific articles,' which positions it relative to jamf_docs_search and jamf_docs_get_article. It also points to jamf_docs_list_products for publication ids. It lacks an explicit when-not (e.g., when to skip the TOC and search directly), so it stops short of the top band.

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/idempotent/openWorld, yet the description adds substantial behavior beyond them: the whole-word rule for terms of 4 characters or fewer, plural/typo tolerance, English-only results even with non-English language params, and a careful distinction between a lookup failure (network/timeout, retryable, 'not a no-match') and a legitimate zero-match result.

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?

Well front-loaded with purpose, then args, returns, examples, and error/no-match semantics in a predictable order. Slight redundancy: the English-only caveat appears twice (once as a standalone note, once in the language arg), and the error section is dense, but nearly every sentence carries load-bearing 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 6-parameter tool with an output schema present, the description covers everything else an agent needs: fuzzy-match behavior, abbreviation rules, the no-op product parameter, truncation via truncatedContent, partial results via incomplete, and the error-vs-no-match distinction. Nothing material 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 baseline is 3, but the description adds real meaning the schema does not: product is accepted yet filters nothing, and language options are accepted but always yield English content. The fuzzy-matching and abbreviation semantics on term also go beyond the schema's example list.

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 (look up a term in the Jamf official glossary) and immediately scopes it: one platform-wide glossary shared by every Jamf product, with fuzzy matching. An agent can distinguish this from jamf_docs_search/get_article because the resource is explicitly the glossary, not documentation articles.

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?

Clear context for when to reach for it (definition lookup of a term) and explicit operational guidance on term length, abbreviations, and that product does not filter. It never names a sibling or says when NOT to use this versus jamf_docs_search, so routing is inferable rather than explicit.

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 genuine behavior beyond that: the `incomplete` failure mode, which underlying sources (maps-registry, jamf-support) can go missing, what each failure costs, and retry guidance. This is rich failure/partial-result disclosure, though it doesn't discuss rate limits or auth.

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 catalogue split is front-loaded and the failure-mode note is well organized. However, the 'Args' section and the 'Returns' block largely restate the input schema and the output schema, so several lines are redundant with structured fields already available to the 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?

With an output schema present, return values are already specified, and the description still supplies the interpretive context an agent needs: what each catalogue is for, which sibling consumes each ID, the truncation mechanism, and the partial-failure behavior. Nothing needed to call 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 coverage is 100% and all three params are documented in the schema, so the baseline is 3. The description goes beyond by explaining why maxTokens defaults higher here ('this one answers with a whole catalogue') and by characterizing 'compact' as a brief list, adding intent the enum alone doesn't 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?

States a specific verb and resource ('List Jamf products, publications, topics, and documentation versions') and immediately splits the response into two named catalogues with distinct downstream uses. It explicitly distinguishes what the list contains from sibling operations by naming jamf_docs_search and jamf_docs_get_toc and their respective parameters.

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

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

Provides four concrete example queries mapped to this tool, plus an explicit exclusion ('These are documents, not products, and the search `product` filter does not take them'). The alternative paths (get_toc with product or publication IDs, search with product filter) are named with the condition that selects them.

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, openWorld), so the bar is lower. The description still adds real value: result ranking by relevance, defined error messages, token truncation info, and the mapId+contentId hand-off/fallback-to-URL behavior. It omits things like rate limits or caching, hence not a 5.

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

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

Purpose is front-loaded and the example block is genuinely useful, but the full JSON/Markdown Returns section duplicates the existing output schema and inflates length. Several Args lines also echo schema descriptions verbatim, so not every sentence 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 an 11-parameter search tool with a full output schema, the description covers errors, ranking, pagination, filtering guidance, and the cross-tool hand-off to jamf_docs_get_article. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by supplying common topic values and a query-to-filter mapping table that shows how the parameters interact, which materially aids invocation despite much of the Args block restating 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 and resource ('Search Jamf documentation for articles matching your query') and scopes it ('across all Jamf product documentation including Jamf Pro, Jamf School...'). An agent can immediately separate this from siblings like jamf_docs_get_article or jamf_docs_list_products.

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

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

Provides concrete context and a rich example set mapping natural-language queries to recommended product/topic filters, and routes the agent to jamf_docs_list_products for ID discovery and jamf_docs_get_article for fetching hits. It stops short of stating when NOT to use it (e.g., vs. batch_get_articles or glossary_lookup), so it is strong but not exhaustive.

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