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

With only readOnlyHint=true in annotations, the description carries the behavioral burden and does so: it details what each view returns, notes that 'occ' yields nothing for Swift-only pages, that non-'page' views read the Swift page, and that invented URLs usually 404. These are real operational constraints an agent could not infer from the 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?

Purpose and return shape are front-loaded, which is good, but the body is one dense paragraph of long nested clauses that is hard to scan. Nearly every sentence carries information, yet the run-on construction and heavy enumeration of view internals cost readability.

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

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

There is no output schema and six parameters, so the description must explain the returns — and it does so per view, per page type and per language, covering everything needed to call the tool correctly and interpret its output.

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 genuine meaning on top: the decision rule for 'similar' (deprecation-note pages first, then See Also, then Topics) and the use case 'for replacing a deprecated API', plus 'occ' semantics for an API's declaration and members.

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 ('Read one page of Apple's developer documentation by its URL') and enumerates the page classes it covers (API, article, sample, tutorial, HIG, ASC Help, endpoint). It also implicitly differentiates from the search/lookup siblings by being the retrieval step for a URL the agent already has.

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?

'Use it on a search result's link or a URL you already have' gives a clear when-to-use condition tied to the sibling search tools, and the url parameter warns that guessed URLs often don't exist. It stops short of naming search_apple_docs explicitly or stating when not to use this tool, so it is clear context rather than full 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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower; the description still adds real value by warning that transcripts are long, with includeTranscript=false as the mitigation, and by noting what the 'related' view returns across all years. It says nothing about failure modes (bad year/videoId) or response size limits for the related list beyond the schema's 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?

The payload enumeration is front-loaded and informative, but the final sentence re-explains the 'related' view mode almost verbatim from the schema, and the whole description is one sprawling colon-chained sentence that is harder to scan than it needs to be.

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 carries the burden of describing return contents, and it does so for both the session and related views, including the time-indexed transcript and code examples. It is complete enough to call correctly, though it omits error/empty-result behavior.

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

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

Schema coverage is 100% and the schema descriptions already explain view, limit, includeCode and includeTranscript, including the tens-of-KB transcript warning. The description's parameter text largely restates those schema strings rather than adding new semantics, so the baseline 3 applies.

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

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

The description names the resource precisely (one WWDC session) and enumerates exactly what comes back: title, year, topics, links/downloads, chapters, timestamped transcript, timestamped code examples, and related sessions. It also covers the alternate 'related' mode, so an agent can distinguish it from search_wwdc_content or list_wwdc_videos without opening the schema.

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

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

It gives conditional guidance for the two modes and for the expensive option ('set includeTranscript to false when you need only the code or the links'), which is exactly when-not-to-use behavior. It does not, however, state when to reach for this tool over the sibling search/list tools, so routing across tools is left implicit.

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 only cover readOnlyHint, so the description carries the disclosure burden and does so richly: per-catalog entry fields, ordering rules (featured first, then library sections), beta marking, per-catalog default limits, and the notable extra behavior of returning a TSV of the whole catalog for grep. This is well beyond what 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?

It is front-loaded with a clear 'Browse four of Apple's catalogs' opening, but at roughly 300 words it is dense and duplicates much of what the catalog enum descriptions already say. The per-catalog sentences carry usage value, yet the catalog re-descriptions do not earn their space.

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

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

For a 9-parameter, four-mode tool with no output schema, the description supplies the return shape per catalog, ordering, defaults, and how to continue with get_apple_doc_content. 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 100% and the schema descriptions are themselves exhaustive (enum meanings, per-catalog filtering semantics, defaults). The description largely restates catalog purposes already documented in the schema, adding only the TSV/grep note, so the baseline 3 is appropriate.

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 the resource and scope precisely (four Apple catalogs), then names each catalog and exactly what it contains (frameworks grouped by category, sample library, updates page, technology overviews). Despite the name suggesting only technologies, an agent can tell this apart from all siblings 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?

Every catalog is paired with an explicit use case ('see which frameworks fit a task', 'find what changed in a framework', 'choose an approach before choosing APIs'), and it names an alternative with its trigger condition: search_apple_docs with type 'sample' for behavioral lookup. get_apple_doc_content is cited for reading 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 only declare readOnlyHint=true, so the description carries the rest, and it does: it discloses the returned fields per session (title, link, topics, transcript/code flags) and the sort order ("newest year first"). It also explains what each view mode counts or returns. It does not mention pagination behavior or the 200-item cap beyond what the schema states, so it stops short of a 5.

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

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

Front-loaded with the core operation and return shape, then routing guidance, then view-mode detail — a sensible order. It is dense but each sentence does work; the trailing view sentence overlaps noticeably with the schema's own view description, which is minor redundancy rather than waste.

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 optional parameters, no required params, and no output schema, the description covers the essentials: what is listed, what fields come back, the ordering, the filter axes, and how it differs from siblings. The three view modes are all touched on. Only pagination/truncation behavior around the limit cap is left implicit, which keeps it just short of complete.

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 every parameter is already documented; the description's restatement of "years" and "topics" views largely duplicates the schema's view description. It adds the framing that these are alternative browse modes rather than filters, but contributes no syntax, default, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("List WWDC sessions") plus scope ("every year since 2014") and the facets it filters by (year, topic, title/topic text). It explicitly names the two nearest siblings — search_wwdc_content and get_wwdc_video — and what each does instead, so an agent can route 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 an explicit use case ("Use it to browse sessions") and contrasts it against both alternatives with their distinguishing behavior: search_wwdc_content "finds what sessions said or showed" and get_wwdc_video "reads one." The view-mode semantics ("years" counts, "topics" lists topics with IDs) further tell the agent which variant to pick.

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 only declare readOnlyHint=true, and the description goes well beyond that: it discloses result ordering ('best match first'), the return shape (links with title, framework, kind, one-line summary), the ranking caveat that a full list means weak matches, and a real constraint (searches run one at a time, 15 s apart). That is unusually rich behavioral context.

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

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

Front-loaded with purpose and the sibling distinction, then usage, then return format, then the rate limit. Dense and parenthetical-heavy ('the way developer.apple.com/search does', repeated quoted examples), but nearly every clause carries routing or behavioral 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?

No output schema exists, and the description compensates by describing exactly what comes back and how to consume it via get_apple_doc_content/get_wwdc_video. Combined with type semantics, ranking caveats, and the rate limit, nothing an agent needs to call this 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%, so the baseline is 3, but the description adds genuine meaning: it explains that omitting type mirrors Apple's unfiltered search, that 'sample' surfaces projects Apple's own library omits, and how word count affects match quality. It stops short of restating query syntax details fully, so not a 5.

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 Apple's developer site'), enumerates the content classes it covers, and explicitly distinguishes itself from search_docs_map ('for a name you already know'). An agent can route between the two search tools without opening either 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 when-to-use with example queries, names the alternative for known-name lookups, and points to get_apple_doc_content and get_wwdc_video for consuming results. The per-type guidance ('for sample code, type "sample"', 'for WWDC sessions, type "video"') is explicit routing advice.

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 only declare readOnlyHint=true, so the description is free to add the behavioral detail it does: result fields (title, kind, Beta/Deprecated mark, technology, parent page, link), ordering (shortest titles first), and the important staleness caveat that pages added after the map's date are missing. These are genuinely useful traits beyond the annotation, though it stops short of noting rate limits or index-source auth/availability.

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 and the query/source distinction are front-loaded and every clause carries information, but the single dense block packs multiple ideas into run-on sentences, making the index/wildcard behavior harder to parse than it needs to be. Slightly more structure would improve scanability.

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 carries the return-value burden and does so, describing match fields and ordering. It also covers the two source modes, staleness, and the follow-up read tool, so an agent has everything needed to invoke 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 description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: plain substring matching on the map versus whole-name wildcards for the index source, and how technology selection narrows sidebars. This meaningfully helps an agent choose values across the source/query/technology combination.

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 (any page of Apple's documentation) and enumerates the covered page kinds precisely. It is immediately distinguishable from siblings like search_apple_docs and get_apple_doc_content, which it names.

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 says when to use it ("when you know a name or part of one, from code, an error or another page") and when not to ("It matches titles only, so to search by what something does, use search_apple_docs"). It also routes to get_apple_doc_content for reading a match and explains the index source for wildcard/family browsing, giving the agent clear alternative-selection logic.

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?

With only readOnlyHint available and no output schema, the description carries the return-shape burden and does so well: ordering ('most matches first', 'newest year first'), per-result contents (match count, first passages and code excerpts, timestamps), and an extra artifact (a folder of every session as text for grepping). This is behavioral context well beyond what the annotation declares.

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 purpose in the first clause and every sentence carries information about behavior or the two view modes. The dense, quote-heavy middle section is somewhat rambling and harder to parse than necessary, but there is no filler.

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

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

For a six-parameter read-only search with no output schema, the description covers corpus scope, both view modes, ranking, result contents, and the sibling to use for follow-up reads. An agent has everything needed to invoke 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 description coverage is 100% and each parameter is documented there, so the baseline is 3. The prose largely restates the schema (view modes, query semantics, type/attribute hints for examples), adding little net-new meaning beyond the structured 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?

States a specific verb (search) and a precisely bounded resource (WWDC session transcripts and code, 2014 onward), and implicitly separates itself from get_wwdc_video and the apple-docs siblings. An agent knows exactly what corpus is being searched 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?

Gives clear context ('Use it to find the sessions that cover an API or a technique') and routes to get_wwdc_video for reading a single session, plus explains when to prefer the 'examples' view over the default. It does not, however, distinguish this tool from search_apple_docs or say when not to use it, so it falls short of full when/when-not coverage.

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