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

Annotations already indicate readOnlyHint=true, and the description adds value by specifying the output (IDs) and their reuse in other tools. No destructive behavior or contradictions.

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 sentences directly convey purpose, usage, and output without waste. Front-loaded with key action and appropriate detail.

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, but the description sufficiently explains the return value (IDs and usage). Parameter meanings are fully covered in schema. Complete enough for an agent.

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%, but the description adds context beyond schema by mentioning that leaving topicId empty shows all topics with video counts, and provides example IDs.

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 tool lists WWDC topic categories with IDs. It distinguishes itself from siblings like 'list_wwdc_videos' by positioning as the essential first step for topic filtering.

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 'Essential first step before using list_wwdc_videos with topic filtering', providing clear context and instruction on when to use this tool.

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=false; the description adds real substance: the payload is written into a local MCP cache, the return is MCP resource links, and non-Apple-hosted links are metadata-only rather than authenticated downloads. It does not contradict the annotation and clarifies mutation side effects the annotation alone would not.

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 tight sentences, front-loaded with the download action and destination, then the exception case. No filler; could be marginally richer on invocation choices but no 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?

No output schema exists, and the description compensates by stating the return is MCP resource links. Combined with a fully documented schema and the cache-write disclosure, an agent has enough to call it correctly; the only thin spot is tool-selection guidance.

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 allowed hosts, size limits/defaults, and the resourceId origin are already documented. The description adds no parameter-level detail beyond noting that selected resources come via list_apple_design_resources, 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?

Names a specific verb (download), resource (Apple Design resource), destination (local MCP cache), and return shape (MCP resource links). It is distinguishable from list_apple_design_resources and the various content-fetching siblings, though it never names an alternative in prose.

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 a useful scope limit — external Figma/Sketch web and sketch:// links are only reported as metadata and are not downloaded — which functions as a when-not condition. However, it offers no explicit guidance on when to call this versus list_apple_design_resources or the content tools, leaving selection 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 establish readOnlyHint=true, so the safe-read profile is covered. The description adds useful relation-type context (prerequisites, follow-ups, thematically similar talks) but omits deeper behavior such as ordering, deduplication, or how the source video's year constrains results.

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

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

Three short sentences, front-loaded with the core action and immediately followed by what it finds and a key use case. No wasted words or buried detail.

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 well to name the kinds of related content returned and frame the learning-path use case. It leaves minor gaps around result structure and ordering, but those are less critical for a read-only discovery tool with fully documented parameters.

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 all six parameters are already documented with examples and defaults. The description mentions no parameters and adds no meaning beyond the schema, making the baseline of 3 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?

States a specific verb (Discover), resource (WWDC sessions related to a specific video), and scope (prerequisite, follow-up, thematically similar). The WWDC-video framing clearly distinguishes it from API-focused siblings like get_related_apis and find_similar_apis.

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 a clear use case ('Essential for creating learning paths') and describes what it finds, but does not state when to prefer this over search_wwdc_content or get_wwdc_video, nor any exclusions. Usage is implied 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=true, which the description supports by using read-only verbs like 'discovers' and 'finds'. However, the description does not add deeper behavioral traits such as result format, pagination, or rate limits. With annotations covering safety, a score of 3 is appropriate.

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 two sentences, front-loaded with the core purpose, and every sentence adds value. No fluff or 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?

Given the tool has 4 parameters and no output schema, the description covers purpose and usage context well. It does not describe the output format, but for a discovery tool, it is mostly complete. Minor gap for a high score.

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 each parameter is already well-documented. The description reinforces the purpose of includeAlternatives but does not add new semantics beyond the schema. Baseline 3 is appropriate when the schema carries the burden.

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 tool finds alternative and related APIs, including similar functionality, modern replacements, and platform-specific alternatives. It distinguishes from sibling tools by emphasizing discovery of better ways to implement functionality.

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 indicates when to use ('Perfect when looking for better ways to implement functionality'), but does not explicitly mention when not to use or contrast with siblings like get_related_apis. It provides clear context but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a real behavioral nuance — HIG pages are served from Apple JSON when available while other /design/ pages fall back to HTML parsing — but says nothing about failure modes, rate limits, or what the returned content looks like.

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 tight sentences with the core action front-loaded and the parsing caveat second. Nothing is wasted, though the second sentence leans toward implementation detail rather than agent-relevant guidance.

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 single-parameter read tool with annotations covering safety and a fully documented schema, this is nearly complete. No output schema exists, so the description could say more about what content is returned, but the essential call contract is clear.

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 there is a single parameter, so the schema already carries the load. The description adds only marginal meaning by indicating the two URL categories the parameter accepts; 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?

States a specific verb+resource: 'Read Apple Design and Human Interface Guidelines URLs.' It implicitly separates itself from the generalist sibling get_apple_doc_content by scoping to /design/ and HIG URLs, though it never names an alternative outright.

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

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

Usage is only implied: the accepted URL shapes (HIG pages vs other /design/ pages) hint at when this tool applies, but there is no explicit when-to-use or when-to-prefer-a-sibling statement against get_apple_doc_content or search_apple_design_docs.

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 supply readOnlyHint, so the description usefully adds that the return payload is base64 image blocks with MIME types, information absent from any structured field. It omits failure modes, rate limits, or behavior when a URL yields no images.

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 sentences, front-loaded with the primary outcome and output format, with zero filler. The second sentence is a compact enumeration of supported input kinds that 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?

With no output schema, explaining the image-block return is valuable, but with four all-optional parameters there is no guidance on how url, query, and resourceId interact or which takes precedence. For a tool whose invocation hinges on picking the right input mode, that gap matters.

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 each parameter is already documented (url, limit, query, resourceId). The description adds no syntax, format, or mutual-exclusion detail beyond the schema, 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 states a specific verb (Return) and resource (Apple Design visual examples) and specifies the output form (MCP image content blocks). It is distinguishable from content-oriented siblings like get_apple_design_content, but it never explicitly names or contrasts with those siblings.

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 hints at usage modes ('HIG images, resource thumbnails, and direct image asset URLs') but gives no explicit when-to-use vs when-not guidance or alternatives across the many siblings. The agent must infer that this is the image-returning counterpart to get_apple_design_content.

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 adds value beyond the readOnlyHint annotation by detailing that the tool retrieves content and supports enhanced analysis options (includeRelatedApis, includeReferences, etc.). No contradictions with 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?

The description is concise (4 sentences) and front-loads the core purpose. Every sentence adds value: positioning after search, mentioning analysis options, and listing best uses. No redundant 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?

Given the tool's complexity (5 parameters, no output schema), the description covers purpose, workflow, and optional features adequately. It does not explain return values, but the schema hints at the output. Still sufficient for an agent to understand when and how to use 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?

With 100% schema description coverage, the input schema already explains each parameter well. The description does not add significant additional meaning beyond what the schema provides, warranting a baseline score of 3.

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 uses a specific verb ('Get') and resource ('content from a specific Apple Developer Documentation page'), clearly distinguishing it from sibling tools like search_apple_docs (which finds pages) and find_similar_apis (which suggests alternatives).

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 explicitly recommends using this after search_apple_docs and lists best use cases (reading API details, understanding usage, checking availability). It does not explicitly exclude other usage scenarios or name alternatives, but the 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 supply readOnlyHint=true, so the safety profile is covered. The description adds useful content-scope detail (what categories of updates are surfaced), but says nothing about auth requirements, pagination, result freshness, or ordering behavior beyond what the schema already states.

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?

Four short sentences, front-loaded with the core capability and ending with the alternative pointer. No filler or repetition of the name, though the "Essential for staying current" sentence is mildly promotional rather than informational.

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 read-only, zero-required-parameter retrieval tool with a fully documented schema and no output schema, the description covers purpose and content scope adequately. It could be tighter on how results are ordered and how year interacts with non-wwdc categories, but nothing critical 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 all six parameters including the year/category coupling and enum values are already documented in the schema. The description adds no parameter-level meaning, so the baseline of 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: tracks Apple platform updates, new APIs, and changes, and enumerates the content types (WWDC announcements, framework updates, release notes). It clearly retrieves documentation news, distinguishing it from content-fetching siblings, though it doesn't name a specific alternative tool 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?

"Essential for staying current with Apple development" is motivational rather than prescriptive, and the only routing hint is a vague pointer to "WWDC-specific tools" for detailed videos. No explicit when-to-use vs. when-not conditions relative to siblings like search_apple_docs or list_wwdc_videos.

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 include readOnlyHint: true, indicating a read operation. The description adds behavioral context by detailing the output (minimum deployment targets, deprecations, platform-specific features) and emphasizing its importance for cross-platform development, going beyond 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?

The description is three sentences: purpose, output, and usage. Every sentence adds value, is front-loaded, and contains no redundant 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 tool with three well-documented parameters and no output schema, the description adequately covers purpose, output, and usage. It lacks details on return format but is sufficient for the agent to decide when to use 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 coverage is 100% with good parameter descriptions (e.g., 'API URL to check compatibility', 'Check single API or entire framework'). The description does not repeat parameter details, but baseline 3 is appropriate since schema already provides sufficient semantics.

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 tool checks API availability across Apple platforms and OS versions, listing outputs like deployment targets and deprecations. It distinguishes itself from siblings by focusing on platform compatibility, a unique function among the listed tools.

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 explicitly includes 'Use when:' with three specific scenarios: planning app requirements, checking API availability, finding platform alternatives. It does not state when not to use or list alternatives, but the provided use cases give clear guidance.

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

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

Description adds details beyond readOnlyHint annotation, such as showing inheritance and protocol conformances. No contradictions; all behavioral traits disclosed.

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 efficient sentences, front-loaded with purpose, no redundancy. Every sentence adds 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 read-only discovery tool with no output schema, the description covers purpose, usage, parameters, and behavioral context adequately. No 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 100%, so the description adds minimal value beyond the schema. The phrase 'Essential for understanding how APIs work together' provides slight context but no extra semantics for parameters.

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?

Clearly states it analyzes API relationships, shows inheritance, protocol conformances, and Apple's recommended alternatives. Distinguishes from siblings like find_similar_apis by focusing on Apple's official recommended alternatives and hierarchy.

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 lists use cases: learning API hierarchy, finding protocol requirements, discovering related functionality. No exclusions, but the context is clear enough for the agent to decide when not to use.

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 include readOnlyHint=true. Description does not contradict and adds context about browsing full sample projects, reinforcing read-only nature. No extra behavioral details needed 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?

Two informative sentences with a third differentiating from sibling. Front-loaded with purpose, no redundant words. Highly concise and structured.

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, but description mentions 'full working examples' which implies the result type. Lacks details on pagination or ordering, but sufficient for a browsing tool given annotations and schema coverage.

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 baseline is 3. Description provides examples for 'framework' and 'searchQuery' but these are already in the parameter descriptions. No additional semantic meaning beyond 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?

Description clearly states 'Browse complete sample projects from Apple' with 'Full working examples' specifying it returns complete projects, not snippets. It explicitly distinguishes from sibling 'search_apple_docs' which returns code snippets.

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 'Use for learning by example', giving clear usage intent. Also contrasts with sibling tool, providing guidance on when to use this vs alternatives. No explicit exclusions, but adequate.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds content-level detail (guides, tutorials) but does not disclose any additional behavioral traits such as rate limits, auth requirements, or pagination behavior. With annotations present, the bar is lower, but no extra behavioral insight is provided.

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 two sentences long, front-loaded with the key verb and resource, and every sentence adds value. No fluff or 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?

Given the lack of an output schema, the description does not detail return values, but it conveys the type of content returned (guides, tutorials, best practices). With 5 well-documented parameters and a clear purpose, the description is fairly complete for a read-only overview tool, though more detail on result structure could help.

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%, with each parameter having a clear description. The tool description does not add any new semantics to the parameters; it only describes the overall content. Per guidelines, baseline 3 is appropriate when schema coverage is high.

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 'access' and the resource 'comprehensive guides and tutorials for Apple technologies'. It specifies the content types (getting started guides, architectural overviews, best practices, implementation patterns) and use case (learning new frameworks, understanding recommended approaches), distinguishing it from sibling tools like get_apple_doc_content or browse_wwdc_topics.

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 clear usage context: 'Perfect for learning new frameworks or understanding Apple's recommended approaches'. However, it does not explicitly state when not to use this tool or how it compares to alternatives like get_apple_doc_content or search_apple_docs, leaving some ambiguity.

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 tells the agent this is a safe read. The description adds that each result includes the code and its session context, which is useful return-shape context. It does not mention pagination, result caps beyond the limit param, or auth, so it adds modest value over 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?

Three short sentences with the core purpose front-loaded and no filler. The 'Perfect for...' clause is mildly promotional but still earns its place by naming use cases. Overall efficient.

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 read-only browse tool with no output schema, the description covers what it does, what results contain (code + session context), and schema fully documents filtering. What's missing is disambiguation from sibling code-search tools, but nothing critical for correct invocation is absent.

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 all five parameters (year, limit, topic, language, framework) are already documented in the schema, including the exact topic-ID examples and language values. The description adds nothing parameter-specific, so 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 states a specific verb and resource: 'Browse all code examples from WWDC sessions.' This is clear enough that an agent knows what it returns (code examples tied to WWDC). It does not, however, distinguish itself from close siblings like get_sample_code or get_apple_design_examples, which likely also return code.

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?

'Perfect for finding implementation patterns, seeing new API usage, or learning by example' implies when to use it, but gives no explicit when-not or alternative routing among the many sibling search/browse tools. The usage context is real but soft, so 3 is appropriate.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the useful note that the result is a self-contained, offline-usable dump of session content, but it says nothing about payload size, rate limits, or whether missing years/IDs fail.

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

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

Three short sentences, front-loaded with the what and followed by the when. Slight redundancy between 'complete WWDC session content' and 'entire session content', but nothing wasteful enough to hurt.

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 right job of naming what comes back, and all four parameters are covered by the schema. Reasonably complete for a straightforward retrieval tool, though it could note failure modes for invalid year/videoId.

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 year, videoId, includeCode, and includeTranscript are all documented in the schema with examples and defaults. The description's mention of transcript/code mirrors those toggles without adding syntax or default behavior beyond 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 ('Access complete WWDC session content') and enumerates what is returned (full transcript, code examples, resources), which clearly separates it from the search/list siblings.

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 routes the agent in a workflow: 'Use after finding videos with list_wwdc_videos or search_wwdc_content.' It names the two feeder tools but gives no when-not condition or signal that the other WWDC tools are alternatives.

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=true, so safety is covered. The description adds useful return-shape context (stable resource IDs, categories, platforms, formats, notes, preview and download URLs), which matters because there is no output schema, but it says nothing about pagination behavior or how the limit interacts with total results.

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 preamble or filler. The field enumeration is somewhat long but earns its place given the absence of an output schema.

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 compensates by naming the returned fields, and the filter set is fully documented in the schema. It falls short of complete only in omitting default/pagination behavior and any routing guidance relative to sibling tools.

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

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

Schema description coverage is 100%, so all five filters (limit, format, category, platform, searchQuery) are already documented with examples in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 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 ('List') and resource ('Apple Design Resources catalog entries'), and enumerates the fields returned. It is clear what the tool does, but it does not differentiate itself from siblings like search_apple_design_docs or get_apple_design_content, which an agent could easily confuse it with.

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 when-to-use guidance is given. The description never explains how this catalog listing differs from search_apple_design_docs or get_apple_design_content, nor when an agent should prefer a filtered listing over a search.

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

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

Annotations already declare readOnlyHint=true, so the bar is lower. The description adds behavioral context like browsing by category, discovering frameworks, and checking beta status, which are helpful but not extensive. It doesn't contradict 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?

The description is only 4 sentences, front-loaded with the main action, and efficiently covers value and usage cases. Every sentence adds information without 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?

The tool is simple with no output schema. The description explains purpose and usage well but could briefly mention the response format (e.g., list of technology names/identifiers). Still, it is largely complete for its 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 coverage is 100%, so baseline is 3. The description adds value by mentioning case-sensitivity for category, providing popular examples, and linking parameter use to real tasks (e.g., checking beta status). This goes beyond schema 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 description clearly states the tool browses Apple technologies by category, using specific verbs like 'browse' and 'discover'. It distinguishes itself from siblings by mentioning the use case of finding framework identifiers for search_framework_symbols, providing a clear resource and differentiator.

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 explicitly lists when to use the tool: exploring available frameworks, finding identifiers, and checking beta status. It references search_framework_symbols as a sibling, providing an alternative. However, it lacks explicit when-not-to-use guidance beyond that.

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 tells the agent this is a safe read. The description does add that transcripts and code are available for 'full offline access', which is useful behavior beyond the annotation. It says nothing about pagination or result ordering, so the added value is modest.

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 with the core verb front-loaded, but 'Shows all available sessions with filtering options' largely restates the opening sentence, and the 'full offline access to transcripts and code' phrase is promotional padding rather than call-relevant guidance.

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 full schema coverage on inputs, the description covers the essentials: discoverability purpose, filtering, and the ability to find videos with code examples. It stops short of stating return shape (title/duration/indicators, which live only in the limit param description) but is largely sufficient.

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%: year, limit, topic, and hasCode are each fully documented with examples and the topic ID enumeration. The description only refers to 'filtering options' generically and contributes no syntax or semantics beyond the schema, so 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: browse/list WWDC session videos with filtering. Distinguishes it from search-oriented siblings (search_wwdc_content, search_apple_docs) by framing it as a browse-all listing. However, it never names those siblings, leaving the browse-vs-search distinction implicit.

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 three implied use cases (discover content, find sessions by topic, identify videos with code), which is clear context for when to reach for it. But it names no alternatives and no exclusions, so the agent must infer why to use this over search_wwdc_content or get_wwdc_video.

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 indicate readOnlyHint=true, so the description adds value by specifying the output includes video counts and statistics. No contradiction, and no hidden behaviors need disclosure for such a simple read-only operation.

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 concise sentences, front-loaded with the main purpose. Every sentence is informative and there is no fluff.

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?

Description adequately covers the return shape (years, video counts, statistics) for a simple list tool with no output schema. The term 'statistics' is vague but acceptable given the context.

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

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

With zero parameters and 100% schema coverage, the description adds meaning by explaining what data the tool returns (video counts and statistics), going beyond the empty 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?

Description clearly states the verb 'list', the resource 'WWDC years', and the data returned (video counts and statistics). It distinguishes from sibling tools like list_wwdc_videos which lists individual videos.

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 explicit guidance on when to use this tool versus alternatives like browse_wwdc_topics or list_wwdc_videos. The description implies it's for an overview of years, but lacks when-not or exclusion criteria.

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

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

Annotations already declare 'readOnlyHint: true', indicating a safe read operation. The description adds that the tool 'resolves all mentioned types', but does not elaborate on performance, scope limits, or other behavioral traits beyond what annotations provide. It does not contradict annotations, but adds minimal extra 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?

The description is concise, with three clear sentences: the action, details, and usage guidance. It is front-loaded with the core purpose and contains no redundant elements.

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 tool has no output schema, yet the description does not explain what the result looks like (e.g., list of references, structure, or metadata). For a tool that resolves references from a documentation page, this is a significant gap. The description would benefit from outlining the return format or 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 input schema already provides detailed descriptions for all three parameters (e.g., sourceUrl example, maxReferences bounds, filterByType enum). The description does not add any parameter semantics beyond the schema. Per guidelines, 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 description clearly states the tool's function: 'Deep dive into all types and APIs referenced in a documentation page. Resolves all mentioned types, methods, and properties.' It uses a specific verb-resource combination and outlines concrete use cases, making the purpose 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?

The description provides explicit when-to-use scenarios ('Use when: analyzing complex APIs, understanding type requirements, exploring API ecosystems'). However, it does not mention when not to use this tool or compare it to sibling tools (e.g., get_related_apis), which slightly limits guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds which corpora are searched (behavioral context), but says nothing about pagination, ranking, or result limits, which matters for a search tool whose behavior the agent must predict.

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 sentences, no filler, with the resource scope front-loaded before the usage list. Every clause carries 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 read-only search tool with fully documented parameters and no output schema, nothing necessary for correct invocation is missing. The only omission, sibling routing, is a minor nice-to-have rather than a blocking gap.

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 query, limit, platform, and contentType are all documented in the schema with examples and defaults. The description repeats the content categories but adds no format or syntax guidance beyond what the schema provides, so 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 (Search) and three concrete resources (Apple Design pages, HIG JSON, Design Resources catalog entries). It is clear what the tool does, though it never names the obvious sibling search_apple_docs to draw the boundary between design-specific and general Apple doc 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 second sentence gives a solid when-to-use list (HIG guidance, design resources, templates, fonts, product bezels, overview pages). It lacks any explicit when-not-to-use or a pointer to search_apple_docs for non-design content, so the routing against siblings remains inferential.

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, so the description carries most of the burden and does well: it discloses expected latency (5-25s, median ~10), the reason (Apple streams full result set), and a 10-minute cache for identical queries. It omits any auth or failure-mode behavior, which keeps it from 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?

Four sentences, zero filler: purpose first, usage guidance second, then performance/caching caveat, then sibling routing. Each sentence carries distinct decision-relevant 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?

Covers purpose, alternatives, latency, and caching for a search tool with no output schema and fully documented parameters. The only gap is a brief note on what results look like or how to page beyond maxResults, which is minor here.

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 schema already documents query tips, the type enum, select semantics, and maxResults interaction. The description adds no per-parameter detail beyond that, 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?

States a specific verb (Search) plus resource (Apple Developer Documentation) and the content classes covered (APIs, frameworks, guides, samples). It explicitly differentiates from siblings by naming get_sample_code and the WWDC tools as separate routes.

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 ('Best for finding specific APIs, classes, or methods') and then routes two other intents away: sample projects to get_sample_code, WWDC videos to list_wwdc_videos/search_wwdc_content. When-to-use and when-not-to-use are both present.

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 provide readOnlyHint=true which is consistent. The description adds no extra behavioral traits such as auth needs, rate limits, or output format. It sufficiently describes the read operation but no additional transparency beyond the purpose.

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 sentences with zero wasted words. Front-loaded with verb and resource, followed by use cases and prerequisite. Highly efficient.

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 is sufficient for a search tool: it tells what it does, when to use it, and hints at output (list of symbols). Missing explicit return type but not critical.

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% with detailed parameter descriptions. The tool description only adds context like 'Get exact names from list_technologies' which is helpful but minimal. 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 description clearly states it browses and searches symbols within a specific Apple framework, uses specific verbs and resource, and distinguishes from siblings by prescribing use after list_technologies.

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 explicitly recommends using after list_technologies and provides example use cases ('exploring framework APIs, finding all views/controllers/delegates'). It lacks direct exclusions but provides clear context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds only the breadth of the corpus being searched; it does not surface the costly Jev rerank path or result volume, though that detail does live in the select/limit schema entries. Adequate but thin beyond what structured fields 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?

Three sentences, all front-loaded: capability, use cases, then sibling differentiation. No filler and nothing an agent needs is buried at the end.

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 7-parameter read-only search tool with a fully documented schema, the description covers capability, scope and differentiation adequately, and no output schema exists so return-format explanation is not owed. It would be a 5 with any note on result ordering or pagination expectations.

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 parameter docs are unusually detailed (limit vs maxResults vs select interaction, year format, enum values), so the schema carries the full semantic load. The description adds nothing parameter-specific, which is the correct baseline when the schema is this complete.

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 (full-text search) plus resource scope (WWDC video transcripts and code examples) and enumerates the concrete intents it serves: discussions, API mentions, implementation examples. It also names the sibling it supersedes, list_wwdc_videos, so an agent can disambiguate 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?

Explicitly routes the agent away from list_wwdc_videos when looking for specific content, which is real when-to-use guidance. It stops short of exclusions (e.g. use get_wwdc_video when you already have an ID) and says nothing about when a narrower tool like get_wwdc_code_examples would be preferable.

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