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

readOnlyHint=true already tells the agent this is a safe read, and the description usefully adds that the data is bundled and requires no network. However, it says nothing about result freshness, pagination beyond the schema's limit, or ordering, so it adds only one genuine behavioral detail.

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 compact sentences, front-loaded with the default (no-topicId) behavior before the alternate mode. Every clause carries information; no filler or repetition.

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 helpfully sketches the return shape (ID, link, session count) and the session-listing mode. Only minor gaps remain, such as ordering or how sessions are shaped when topicId is supplied.

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%, including the full topicId enum list and defaults for limit and includeVideos, so the schema carries the burden. The description only restates year filtering and limit capping, adding no meaning 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?

The description names a concrete resource (WWDC topics) and spells out the two operating modes: listing all topics with ID/link/session count, or drilling into one topic's sessions. It is clear enough to distinguish from siblings like list_wwdc_videos, though it never names an alternative explicitly.

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 implicitly explains the mode switch (pass topicId to get sessions instead of topics), but gives no guidance on when to choose this over list_wwdc_videos, search_wwdc_content, or list_wwdc_years, all of which overlap with topic browsing.

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=true, so the description carries extra weight and delivers: it discloses the data source is bundled/local ('no network'), describes the deterministic relation ranking, and enumerates return fields (year, link, topics, transcript/code presence). It adds real context beyond the annotation, though it says nothing about result caps or error behavior.

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

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

A single front-loaded sentence that opens with the core purpose and then elaborates the ranking and return shape. It is dense with semicolons and a parenthetical, which slightly slows parsing, but almost every clause carries information and 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 read-only lookup with full schema coverage and no output schema, the description is nearly sufficient: it explains the data source, the relation sources/order, and the fields returned. The one meaningful gap is guidance on choosing it over sibling search/list tools, which leaves 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 coverage is 100%, so baseline would be 3, but the description goes further by tying the flags to the retrieval semantics: 'those Apple lists as related' maps to includeExplicitRelated, 'sharing its topics' to includeTopicRelated, and 'with includeYearRelated' to the same-year expansion, establishing the precedence order the schema does not express. The limit parameter is left unaddressed, keeping it from 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+resource ('Sessions related to one WWDC session') and clarifies the scope with 'from the bundled data (no network)'. A reader immediately understands this returns related sessions for a given session. It does not, however, distinguish itself from siblings like get_wwdc_video or search_wwdc_content, so it stops short of a 5.

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

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

The description implies the scenario (find sessions related to a given session) and explains the ordering/precedence of relations, but never states when to pick this tool over alternatives such as search_wwdc_content, browse_wwdc_topics or get_wwdc_video. Usage is implied rather than explicit, and there are no exclusions or prerequisites.

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 already establishes the safe-read profile, and the description adds genuinely non-obvious behavior: results are read from the page's JSON, prioritization tiers (deprecation note 10/10, See Also 8/10, Topics 6/10), and the clarifying note that scores reflect provenance rather than similarity comparison. This is meaningful context beyond the annotation.

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 content is front-loaded with the core purpose, but it is delivered as one long, heavily nested sentence with parenthetical scores and quoted enum values, making it denser 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?

For a read-only, fully-documented-parameter tool with no output schema, the description conveys enough about what comes back (ranked alternatives with provenance scores) and how depth affects results. It is close to complete, lacking only sibling routing.

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 schema already documents all four parameters including the depth enum. The description only adds marginal nuance (which groups each depth reaches), 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 opening 'Alternatives to one API' states the resource and outcome clearly, and the rest explains how alternatives are sourced. It does not, however, name or distinguish itself from the obvious sibling get_related_apis, so an agent must infer the division of labor.

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 through the searchDepth mechanics (medium/deep reaching Topics groups, deep reading See Also of first results). There is no explicit statement of when to pick this over get_related_apis or search_apple_docs, nor any when-not condition.

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 the safety profile is already covered, and the description adds substantial behavioral context on top: it explains what the response contains per page type, that links arrive as links, and that the include flags are read from the source JSON and append related data. The notable gap is pagination: 'One page' implies a continuation mechanism, but nothing explains how to fetch subsequent pages or whether the include flags inflate response size/cost.

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

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

The body is essentially a single ~190-word run-on sentence built from semicolon-separated clauses with no line breaks or headings. The most decision-relevant fact, the include-flag behavior, is buried at the very end rather than front-loaded, and the enumeration of every possible payload field is far larger than an agent needs to select the tool.

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 exhaustively across page types, which is genuinely useful. However, for a tool explicitly framed as delivering 'one page,' the absence of any pagination or continuation guidance leaves a functional hole, and error behavior for unsupported URLs is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents the url constraint and each include flag's meaning, which sets the baseline at 3. The description only loosely restates the flags' effects ('append related APIs, referenced types, similar APIs and a platform analysis'), adding no format, cost, or interaction detail 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?

The description clearly states a specific verb and resource: it returns one page of Apple Developer documentation rendered as Markdown from the page's source JSON. It also usefully signals that the payload differs by page type. What it lacks is any differentiation from siblings such as search_apple_docs, get_sample_code, or get_related_apis, and the run-on phrasing makes the core purpose harder to extract than it should be.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no naming of alternatives, despite 18 sibling tools that overlap in domain (search_apple_docs, get_sample_code, get_related_apis). The only usage-adjacent statement is the trailing note that the include flags append extra data, which does not tell an agent when to pick this tool 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 safety is covered. The description adds a genuinely useful behavioral fact beyond the annotations: the response is metadata links rather than content, and it enumerates what categories appear in the output. It stops short of describing pagination or result ordering, but the added context is solid.

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

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

The core action is front-loaded and each claim earns its place, including the scope enumeration and the sibling routing. It is dense but not padded; the only minor cost is that the scope list and routing are packed tightly together.

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 correctly compensates by stating that it returns links rather than changes and by enumerating the link scopes. Combined with full schema parameter coverage and the readOnlyHint annotation, an agent has enough to invoke it correctly; only pagination/ordering behavior is left implicit.

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 (year, limit, category, technology, includeBeta, searchQuery) are already documented in the schema. The description's mention of scope categories maps onto the existing category enum and adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb and resource: it returns links from Apple's Updates page with one-line summaries, and enumerates the covered scopes (OS/Xcode/Safari release notes, framework updates pages, WWDC What's new pages). It explicitly contrasts itself with siblings by warning that it returns links, not changes, and points to get_apple_doc_content and the WWDC tools for other needs.

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 explicit routing: use this tool for the links, read a single item with get_apple_doc_content, and use the WWDC tools for sessions. This is when-to-use plus named alternatives with the condition that selects each, leaving nothing 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?

With only readOnlyHint=true in annotations, the description carries the return-value burden and does so well: it discloses per-platform version ranges, Apple's note text, minimum versions, and the special 'deprecated on every supported platform' flag. It stops short of covering failure modes or how the page JSON is fetched, but adds genuine context beyond the annotation.

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, but the first is a dense run-on whose front-loaded clause ('Where one API is available, from its page's JSON') reads awkwardly before the useful content. All the material earns its place, yet the structure could be far cleaner.

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, so the description must—and does—explain what comes back, including the deprecation flag and the framework compare mode. It omits guidance on includeRelated and the expected URL form, minor gaps for a single-resource read tool with full 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% with only 3 parameters, so the baseline is 3. The description's note on compareMode "framework" largely restates the schema's own enum description, and it never mentions includeRelated, so it adds little semantic value over the structured fields.

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 (an API's platform availability from its page JSON) and enumerates exactly what is returned: per-platform introduced/deprecated versions, Apple's note, minimum versions, and a deprecation flag. The awkward opening ('Where one API is available') slightly muddies the verb, but an agent can tell this apart from search_apple_docs or get_related_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?

It gives one routing hint — compareMode "framework" runs the same check with related APIs included — but there is no explicit when-to-use vs siblings like get_related_apis or find_similar_apis, and no prerequisites (e.g. that apiUrl must be a developer.apple.com documentation URL). Usage is implied rather than stated.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: the data source is the page's JSON alone (not a crawl or graph), and Topics groups are truncated to the first 3 APIs. These are real constraints an agent should know. It does not cover failure modes for invalid URLs or any rate limiting, so 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?

A single sentence that is front-loaded with the resource and packed with specifics rather than filler. It is dense and slightly run-on, but every clause (source, categories, caps, return shape) contributes 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?

With no output schema, the description carries the return-value burden and does so: it states each API comes with its link and Apple's one-line summary, plus the grouping and caps. Error handling and pagination are unaddressed, which keeps it from a 5 but it is otherwise sufficient for a read-only lookup tool.

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

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

Schema coverage is 100% and each boolean parameter already has a clear description, so the schema carries the load. The description reinforces what the inherit/conformance/See Also categories yield, but adds no syntax or defaults beyond what the schema states. 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 a specific resource (the APIs a documentation page relates to) and enumerates exactly what is returned: inheritance, conformances, the See Also group, and the first 3 APIs per Topics group. The phrase 'read from that page's JSON alone' implicitly separates it from similarity-based siblings like find_similar_apis, though that sibling is never named explicitly.

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: an agent can infer you call this to discover related APIs for a given doc URL. There is no explicit when-to-use statement, no guidance on when find_similar_apis or search_framework_symbols would be the better choice, and no prerequisites mentioned.

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 declares this is a safe read. The description adds genuine behavioral context beyond that: results are relevance-ordered with title matches ranked first, then frameworks/paths/summaries. It omits return shape, pagination, and what happens with zero filters.

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 resource, but the first sentence is a dense run-on mixing output description and a routing hint to get_apple_doc_content. The trailing sentence packs two separate matching rules into one clause chain, which hurts scannability.

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 carry burden and does describe the returned content, but it never mentions pagination despite the limit (max 200) parameter, nor what an unfiltered call returns. Adequate but with visible gaps for a 4-param listing tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining that framework matches in any spelling/fuzzy form ("storekit" vs "Store Kit") and that searchQuery ranking prioritizes titles over frameworks, paths and summaries. It leaves beta/limit semantics to the schema, which is acceptable.

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 resource (Apple's sample-code library) and what it returns: project titles, links, one-line summaries grouped by framework, plus the ability to read a project page. It gestures at a sibling (get_apple_doc_content for a project's page) but does not clearly distinguish itself from search_apple_docs or search_wwdc_content.

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

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

Usage is implied through the parameter guidance ('searchQuery matches titles first...') and the pointer to get_apple_doc_content for reading a page, but it never states when to choose this tool over search_apple_docs or search_wwdc_code_examples. No explicit when-not conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that, the description adds real behavioral context: results are links rather than article contents, ordering follows Apple's own order, and an unknown category falls back to the full list. Return formatting is only lightly sketched (tree vs flat list), so it stops just short of 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-loads what the tool returns, then mode behavior, then the hand-off to get_apple_doc_content — no wasted sentences. The prose is densely packed with semicolons, which is efficient but slightly harder to parse than a cleanly separated set of clauses.

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 most of the work by explaining that entries are links in an ordered tree or flat list, each tagged with its collection. It falls short only on pagination/limit interaction with the two modes, which the agent must infer from the schema's limit field.

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 each field is already documented, but the description adds mode-level meaning the schema doesn't: category yields a whole collection plus children, searchQuery yields a flat cross-collection match list, and includeSubcategories governs whether articles appear at all. This meaningfully exceeds the baseline 3 for a fully-documented schema.

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

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

States a specific verb+resource: retrieving Apple's Technology Overviews guides as a tree of collections and articles. It also distinguishes itself from the siblings by naming get_apple_doc_content as the tool for reading the actual articles, so an agent needn't open other schemas to disambiguate.

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 between modes: category returns one collection with everything in it, searchQuery returns a flat list of matching entries, and empty/unknown values return the full list. It also states the read-elsewhere alternative ('read one with get_apple_doc_content'), closing the loop on when not 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?

The readOnlyHint annotation already covers the safety profile, and the description adds real value beyond it: 'no network' tells the agent results come from bundled local data, and it discloses the shape of each returned example. It does not mention result-count truncation or pagination, but the schema's limit parameter largely covers that.

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 that leads with the resource and provenance before detailing filter behavior. Dense but every clause carries information; the only cost is that the filter explanation is a run-on chain rather than split into digestible points.

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 5 optional params, no output schema, and a read-only annotation, the description supplies what an agent needs: what a result contains and how each filter behaves. Only the interaction between limit/default truncation and filtering is left entirely to the schema.

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 genuinely adds semantics the schema lacks: framework matching is substring-on-code ('SwiftUI matches any code that imports SwiftUI') rather than an exact framework name. This disambiguates a filter whose behavior is otherwise guessable.

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 concrete verb+resource ('Code examples from the bundled WWDC sessions') and enumerates the returned fields (title, session title, link, year, timestamp, code). It is clearly distinguishable from sibling tools like get_sample_code because it specifies WWDC sessions and bundled/local data, though it never names an alternative explicitly.

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 filter semantics ('framework keeps the examples whose code mentions it', 'topic, language and year filter too') tell the agent how to narrow results but not when to pick this tool over search_wwdc_content, get_sample_code, or find_related_wwdc_videos. No when-not guidance or prerequisites are given.

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

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

Beyond readOnlyHint=true, the description discloses that data is bundled (no network) and warns that transcripts run to tens of KB, with includeTranscript=false omitting them. That payload-size context is genuinely useful and not derivable 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?

The purpose and 'no network' scoping are front-loaded, and the colon-list of returned fields is dense but scannable. The payload warning is placed at the end where it is most actionable; the single long sentence is slightly run-on but not wasteful.

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 itself and does so thoroughly: title, year, topics, HD/SD download links, covered docs, transcript, timestamped code examples, and related sessions. Combined with readOnlyHint and the size caveat, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the practical consequence of includeTranscript (transcripts can be tens of KB, set false to omit), which adds meaning about why and when to flip the flag rather than just restating its default.

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 (retrieve one WWDC session) and delineates scope ('the bundled data, as text (no network)'), then enumerates exactly what the session record contains. An agent can tell it apart from list/search siblings, though no sibling is named explicitly.

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

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

Usage is implied by the getter shape (one session keyed by year + videoId), and the includeTranscript note hints at the token-cost tradeoff. However, there is no explicit when-to-use guidance and no mention of alternatives such as search_wwdc_content or get_wwdc_code_examples.

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 most of the burden and does so: it discloses alphabetical-within-category ordering, that beta entries are suffixed "(Beta)", and the two-stage category matching rule (category name contains X, else tag contains X). Missing only return-size/pagination behavior beyond the limit param.

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 long, somewhat run-on sentences with nested parentheticals and repeated quotes; the key identifying facts are front-loaded, but the schema-duplicating category explanation and dangling clause "in any case" add clutter rather than 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?

With no output schema, the description must convey the return shape, and it does: per-category alphabetical listing, frameworks with links, language tags, categories, and beta marking. It does not mention result-size behavior or the default 200-per-category cap, which the schema covers but a caller might still want surfaced.

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 all four parameters including the category matching rule and the beta filter. The description largely restates the category semantics ("in any case") and links the beta marking to includeBeta, adding only marginal meaning 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?

Opens with a specific verb+resource framing ("Apple's technology index: every framework and technology with its link, its languages ... and its categories"), so the agent knows exactly what comes back. It also distinguishes itself from search_framework_symbols by explaining that the last link segment is the framework that sibling accepts.

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 category semantics and the hand-off note to search_framework_symbols imply when this tool is useful (browsing/discovering frameworks by category or tag). However, there is no explicit when-to-use guidance versus siblings like get_technology_overviews, search_docs_map or search_apple_docs, and no statement of when NOT to use it.

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 genuinely new behavioral context — the data is bundled locally with no network access — but says nothing about ordering, pagination behavior for large result sets, or what happens when filters match nothing.

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 a single compact block with no wasted sentences and leads with what the tool returns. It is somewhat crammed with parenthetical asides, which slightly hurts readability, but nothing is 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?

With four optional params and no output schema, the description does state what each result contains (title, link, transcript/code, topics). It omits any note about result ordering or the effect of the limit default, which is a minor gap for a list tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description largely restates those semantics ('year is one year or all', 'hasCode keeps the sessions with, or without, code') without adding syntax or default details 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 (list) and resource (WWDC sessions) and enumerates the returned fields (title, developer.apple.com link, transcript/code flags, topics). It also scopes the data source ('bundled with this server, no network'), which separates it from network-backed siblings like search_wwdc_content.

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 routes parameter values to helpers (list_wwdc_years for years, browse_wwdc_topics for topic IDs), which is useful implicit guidance. However, it never says when to choose this tool over alternatives such as search_wwdc_content or find_related_wwdc_videos, so the tool-selection guidance is only implied.

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 usefully discloses the return shape — per-year session counts plus totals for code and transcript availability — rather than leaving an agent blind, which matters since there is no output schema. It does not mention the data source freshness or format beyond 'bundled data'.

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 boilerplate. It is packed with several clauses (per-year counts, totals, code/transcript counts) but each clause conveys distinct return information, so nothing is wasted.

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

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

With no output schema and no parameters, the description bears the burden of explaining what comes back, and it does so adequately for a fixed-shape listing tool. The main gap is the absence of any routing guidance among the many 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify on the input side; the schema is trivially 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 resource (WWDC years) and describes the exact payload: per-year session counts plus aggregate totals for sessions with code and transcripts. This distinguishes it from siblings like list_wwdc_videos or browse_wwdc_topics, though it never names an alternative explicitly.

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 whatsoever. With 19 sibling tools in the WWDC/doc space, the agent gets no signal about when to reach for this year-level rollup versus search_wwdc_content, browse_wwdc_topics, 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?

With only readOnlyHint=true in the annotations, the description carries real behavioral weight: it discloses that no additional network requests are made, that results are truncated by JSON order rather than relevance, that images/media are excluded, and that output is grouped by kind. That is substantive context beyond the annotation, though it stops short of covering failure modes or invalid-URL behavior.

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

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

It is a single dense sentence with parenthetical asides, but the core purpose is front-loaded and the trailing clauses (ordering, exclusions, filter) each add distinct information. Slightly over-packed for one sentence, but no clause is 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?

With no output schema, the description must describe the return shape, and it does: title, kind, Apple's summary, and declaration for symbols, grouped by kind. Combined with the ordering and exclusion notes, an agent has enough to call and interpret the tool, with only error/edge-case behavior left unstated.

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 meaning the schema does not: maxReferences is explicitly ordering-semantic ('the first maxReferences in the JSON's own order, not by relevance'), and filterByType is characterized as keeping 'one role or kind'. Those are genuine semantic additions rather than restatements.

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-resource pairing: it returns the pages that a given documentation page references, scoped explicitly to what is derivable 'from that page's JSON alone (no further requests)'. This clearly separates it from the sibling search_* and browse_* tools, though it never names an alternative directly, which keeps it short of a 5.

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

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

Usage is implied rather than stated: the agent can infer it should call this to enumerate a page's outbound references, and it gives ordering/limit guidance ('first maxReferences in the JSON's own order, not by relevance'). However, there is no explicit when-to-use versus search_apple_docs or get_apple_doc_content, nor any stated exclusion or prerequisite condition.

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; the description adds genuinely useful behavior beyond that: results are links grouped by section, 'all' triggers two requests, searches are serialized 15 s apart because Apple returns empty for rapid ones, and 'all' includes a capped 5-session WWDC block. These are operational details an agent cannot infer from the schema.

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 return shape, then filters, then the reading alternative, then rate behavior. Dense but each clause carries information; only slight compression of the rate-limit sentence could tighten it further.

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

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

No output schema exists, yet the description fully specifies the return shape (title, framework, type, one-line summary, grouped by section) plus the alternative reader and rate constraints. 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%, so the enum values are already documented, but the description adds meaning beyond the schema: 'all' sends two searches (rate/time implications) and the WWDC Sessions section behavior. This goes past restating the enum, though it does not add syntax guidance for query.

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 (search developer.apple.com via Apple's search API) and immediately distinguishes the return type from content-returning siblings: 'Returns links, not content'. An agent knows exactly what this produces versus get_apple_doc_content.

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 names the alternative for reading results ('Read a result with get_apple_doc_content') and explains what each type filter covers, so the agent can pick the right scope without guessing. It also routes WWDC Sessions results to 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?

Beyond readOnlyHint, the description discloses that results come from a local prebuilt file (api-map/apple-docs-map.tsv, no network), that matching is title-only and literal, that results are sorted shortest-titles-first, and that technology may retain multiple frameworks. Those are genuine behavioral traits not covered by the annotation. It does not discuss result caps or pagination, but the schema's limit already handles that.

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 dense with useful detail, but the whole description is a single long run-on sentence with stacked parentheticals. The build-path implementation details (scripts/build-docs-map.ts) add little for an invoking agent, though the rest of the content 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, the description usefully enumerates the returned fields (title, kind, technology, link) and their ordering, and points to get_apple_doc_content for follow-up, which is enough for a read-only search tool. Missing only explicit guidance on the search_apple_docs alternative.

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 query, limit and technology are already documented in the schema, including the literal-match behavior and the shortest-titles-first limit semantics. The description adds only marginal nuance ("technology keeps one or more frameworks"), so it sits at the baseline for fully-described 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?

States a specific verb and resource (search the docs map) plus the exact matching rule (title contains query, any case, as typed, no pattern syntax) and the data source, so an agent can tell it mirrors over a local static map rather than the live API. It stops short of explicitly contrasting with the closely-related sibling search_apple_docs, leaving the agent to infer which search to pick.

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 a follow-up instruction ("Read a page with get_apple_doc_content") and a constraint (no pattern syntax), which shapes how to use it. It offers no explicit when-to-use/when-not guidance relative to search_apple_docs, the sibling an agent would most likely confuse it with, so usage is only implied.

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 safety profile is covered. The description adds useful behavioral context beyond annotations: results omit summaries, nested symbols count toward the limit, and namePattern matching is case-insensitive. It does not discuss pagination or failure cases, but for a read-only index search this is solid.

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 compact and front-loaded: it starts with what the tool returns, then parameter clarifications, then the follow-up tool. Every sentence carries information, and semicolons keep it dense without 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?

Given five parameters, no output schema, and only a readOnly annotation, the description covers the essential return shape (name, link, kind, no summaries) and the core filtering behavior. It stops short of specifying pagination or full output structure, but it provides enough for an agent to call the tool 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 schema already documents all five parameters with examples. The description adds the useful detail that framework is the last segment of the documentation link, but much of its parameter text repeats schema content such as the limit including nested symbols and namePattern case-insensitivity. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource and scope: symbols from one framework's navigator index, with name, link, and kind but no summaries. It distinguishes this from full-content retrieval by naming get_apple_doc_content, so an agent can tell it apart from siblings such as search_apple_docs.

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 clear context: use a framework identifier obtained from list_technologies, filter by symbolType, and use namePattern for wildcard matching. It also names get_apple_doc_content as the next step for reading a symbol. However, it does not explicitly say when to prefer this tool over search_apple_docs or other search siblings.

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 behavioral burden and does well: it discloses that the corpus is local/bundled (no network), that results are ranked most-matches-first, and describes the actual return shape (title, link, year, up to 3 matches with snippets). It doesn't mention pagination or result limits beyond the schema, but the added disclosure is substantial.

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 a single dense sentence that front-loads purpose before spilling into return-format detail. Nothing is wasted, though the return-format clause makes it longer than strictly needed for selection.

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 describing the result shape. All 5 parameters are covered and the offline nature is disclosed, leaving only sibling routing as an unaddressed 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 coverage is 100%, so the baseline is 3. The description adds a small amount of meaning by clarifying that searchIn toggles transcript vs code and that language only applies to code, but this largely restates what the schema already documents.

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 ("Full-text search of the bundled WWDC transcripts and code") plus a scope qualifier ("no network") that separates it from sibling doc/symbol search tools. An agent can distinguish it from search_apple_docs or search_framework_symbols without opening the schema.

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

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

The description explains how searchIn and language shape the search, which is genuine usage guidance at the parameter level. However, it never states when to pick this tool over alternatives like search_apple_docs or find_related_wwdc_videos, so inter-tool routing is left to inference.

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