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

The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so safety is fully covered. The description adds the data source (apple_docs index) and the two pieces of information returned, but says nothing about index coverage limits, lookup failures for unknown symbols, or how deprecation is reported.

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 primary capability; the second sentence about the apple_docs index earns its place as a scope signal. No filler or repetition of the title.

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 only two parameters and no output schema, the description does indicate the content of the answer (introduced-in version plus deprecation status), which is the main thing an agent needs. It stops short of covering not-found behavior or output shape, but the tool is simple enough that this is a minor 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%: api_name is documented with concrete examples ("SwiftUI.View", "UITableView") and format has an enum with a default. The description adds no extra meaning about the symbol-name format, framework prefixing, or the effect of choosing json vs markdown, 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?

It states a specific verb and resource — looking up the minimum OS version an Apple API was introduced in, plus deprecation status — which is concrete and unambiguous. It does not, however, distinguish itself from close siblings such as apple_api_deprecation, wwdc_find_api_introduction, or apple_what_replaced, so an agent cannot tell from the description alone which one 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named despite several siblings covering overlapping ground (apple_api_deprecation for deprecation, wwdc_find_api_introduction for introduction versions). The only scoping signal is the implicit statement that it queries the apple_docs index, which hints at coverage but does not guide tool selection.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the lookup is by symbol name and what facts come back, but says nothing about coverage limits (which SDKs/versions), failure behavior for unknown symbols, or the format parameter's effect.

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 core purpose and then the lookup key. Nothing redundant and 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?

With no output schema, the description usefully previews the return shape (deprecation status, deprecation date, replacement symbol), which is the main thing an agent needs. It is slightly incomplete on scope boundaries (SDK/version coverage) and the format option, but adequate for a simple read-only lookup.

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 both api_name and the format enum. The description's examples (UIWebView, UIAlertView) duplicate the schema's own example text and it never mentions the format parameter, so it adds essentially no semantic value beyond 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?

States a specific verb (check) and resource (Apple API symbol deprecation status), and enumerates the three facts returned: deprecated?, when, and replacement. It does not explicitly distinguish itself from close siblings like apple_api_availability or apple_what_replaced, which cover overlapping territory, 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?

"Looks up by symbol name (e.g. UIWebView, UIAlertView)" implies the usage context and input shape, but there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as apple_api_availability or apple_what_replaced for adjacent questions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: the graph must first be populated with `npm run ingest -- --source cross-reference`, which tells the agent why results could be empty. It stops short of describing pagination or edge metadata.

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, both front-loaded: the first defines the operation and directionality, the second supplies use cases and the data prerequisite. No filler, no repetition of the title.

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 graph query with no output schema and fully documented parameters, the description covers operation, directionality, use cases and a setup prerequisite. The main remaining gap is what an edge record actually contains (edge type/label), which the agent would have to discover at call time.

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 a clear enum gloss for `direction`, so the schema carries the parameter burden and baseline is 3. The phrase 'outgoing and/or incoming edges' loosely mirrors the `direction` parameter but adds no syntax or semantics beyond what the schema already states.

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 gives a specific verb and resource: 'Returns outgoing and/or incoming edges from the cross-reference graph for a given entity', with concrete examples of what those edges represent. It is clear what the tool does, but it never differentiates itself from overlapping siblings such as wwdc_related_sessions or wwdc_sessions_for_api, which cover some of the same questions.

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 supplies concrete when-to-use scenarios ('which sessions mention an API', 'which proposals a session implements', 'related sessions'), which is stronger than implied usage. However, it names no exclusions or alternative tools, so the agent must infer when a sibling would be a better choice.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that content comes from a local index (implying no live network fetch), but says nothing about truncation behavior, missing-path handling, or how format changes the response. Adds some value over annotations, but not much.

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 an inline example and zero filler. It is efficient, though for a four-parameter tool with half its schema undocumented it is arguably under-sized rather than optimally scoped.

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

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

No output schema exists, so the description should carry more of the return contract, yet it does not explain markdown vs json output or the body_chars truncation. Annotations cover safety and the retrieval semantics are simple enough that the gap is moderate rather than severe.

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 only 50%: body_chars and include_raw have no description in either schema or prose, leaving truncation length and raw-content inclusion undocumented. The description does add real value for the required param by specifying a 'normalized path' with the concrete example `swiftui/view`, which goes beyond the schema's terse 'Framework path or Apple documentation URL.'

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 ('Return an Apple Developer documentation page') plus the source ('from the local index'), so the agent knows this is a direct retrieval rather than a search. However, it never distinguishes itself from the near-identically named sibling apple_doc_lookup, leaving the agent to guess which of the two 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?

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives such as apple_doc_lookup or apple_doc_list_framework. The example path is invocation help, not selection guidance, so the agent gets no routing signal.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral detail beyond that - the matching mechanism ('modules JSON array and doc path prefix') - which explains why a framework name resolves to results, but says nothing about pagination, result ordering, or return shape.

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 with the primary purpose front-loaded and the matching rule following immediately. No filler, though the second sentence leans toward implementation detail rather than agent-facing 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 5-parameter listing tool with no output schema, the description covers what is listed and how the framework filter resolves, but omits result limits/pagination behavior and the effect of the 'format' enum. Annotations carry the safety side, but the listing/pagination behavior an agent needs is left to the schema defaults.

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 60%, and the description clarifies the semantically loaded parameter (framework) as a name matched against module arrays and doc path prefixes, which the schema only illustrates with examples. However, it adds nothing about 'type', 'limit', 'offset', or 'format', so the remaining gaps are only partially compensated.

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 ('Browse'/'List') and resource ('indexed Apple documentation symbols and articles') scoped to a framework or module, which matches the title. It does not explicitly name how it differs from siblings like apple_doc_lookup or apple_doc_get, so an agent must infer that this is the enumeration path versus the retrieval paths.

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?

'Browse all ... for a framework or module' implies the use case (enumerate a framework's symbols) but gives no explicit when-to-use vs when-not guidance and no mention of alternatives such as apple_doc_lookup for targeted retrieval. 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds one behavioral fact beyond annotations — 'Returns live data (no cache)' — but omits return format details, error behavior, or how the format parameter affects output.

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 short sentences, front-loaded with the core action and examples, then a compact operational note. Zero waste and easy to scan.

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 simple read-only lookup with rich annotations and full schema coverage, the description provides purpose, path examples, and a live-data caveat. It lacks sibling differentiation and format details, but those gaps are minor given the structured data available.

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 fully documents both 'path' and 'format'. The description repeats path examples but adds no syntax or semantic details beyond what the schema already provides. 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 (Fetch) and resource (Apple /documentation JSON node) with concrete path examples. It does not differentiate itself from sibling tools like apple_doc_get or apple_doc_list_framework, so it's clear but lacks sibling routing.

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 no when-to-use, when-not-to-use, or alternative selection guidance. The examples illustrate path format but give no context for choosing this tool over siblings such as apple_doc_get.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds meaningful context beyond them: the data source is RSS-ingested forum posts (implying completeness/freshness limits), and results are ranked posts with title, URL, and snippet — useful given there is no output schema. It still omits pagination/ranking behavior and freshness lag.

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 scope, with no redundancy. The middle sentence listing frameworks is mildly decorative but still conveys coverage boundaries.

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 covers the return shape, and annotations cover the safety profile. What remains missing is pagination behavior plus any differentiation from the overlapping swift_forum_search sibling — an agent could reasonably pick the wrong forum 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 50%: query and format are documented in the schema, but limit and offset carry no descriptions anywhere. The description adds essentially nothing about parameters beyond implying free-text querying via 'full-text search' and 'ranked posts'; it never mentions paging, result cap, or the markdown/json format option.

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 ('Full-text search across Apple Developer Forums posts') and names the content scope (SwiftUI, Swift, Combine, recent discussions), so the agent knows exactly what is searched. However, it never distinguishes itself from the near-identical sibling swift_forum_search, nor from the broader apple_search_all, leaving a real disambiguation gap.

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 statement of when to prefer this tool over swift_forum_search, apple_hig_search, apple_release_notes_search, or apple_search_all. The phrase 'other recent developer discussions' hints at a recency/coverage boundary but provides no actionable when-to-use or when-not-to-use 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a real behavioral trait ('groups results by category'), but says nothing about pagination despite limit/offset params, nor return format. Adds some value but not rich 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?

Two tightly written sentences, front-loading what the tool does before the alternative routing. Nothing is redundant and no sentence 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?

No output schema exists, and the description supplies the key return-shape fact (grouped by category) plus filter routing. Minor gaps remain around pagination and the format parameter, but an agent has enough 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 60%, and the schema already carries descriptions for keyword, section, and format. The description restates the category/keyword filters and adds example values, but leaves limit/offset/format unexplained, which is baseline-adequate rather than additive.

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'), resource ('HIG entries'), and scope (optional category/keyword filters, grouped by category). It also names the sibling it is not ('apple_hig_search'), so an agent can distinguish browse-vs-search without opening a schema.

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

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

Explicitly routes between this tool and the alternative: 'Use apple_hig_search for full-text FTS search; use this to browse by category.' It gives the selecting condition and concrete category examples ('Foundations', 'Components', 'Inputs').

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context of its own: nothing about ranking, snippet content, truncation via limit, or the default markdown response.

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?

One tight sentence with the core scope front-loaded and no filler. It is efficient, though bordering on under-specified for a three-parameter 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?

No output schema exists, so the description should carry more of the burden, yet it omits return shape, result limits, and how results differ from apple_hig_list. For a search tool with sibling overlap and partial schema coverage, this is thin.

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 only 33% – just the 'format' enum has a description. The description's phrase 'keyword search' hints at query matching semantics but says nothing about the limit caps or what the query string accepts, so it only partially compensates for the undocumented 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 (keyword search) and resource (HIG topics), scoped to components, patterns and platforms. An agent can tell it apart from apple_hig_list by the search semantics, 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?

No when-to-use guidance and no exclusions. Nothing tells the agent when to prefer this over apple_hig_list, appstore_guidelines_search, or the broader apple_search_all, so the choice must be inferred from the name alone.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that results come back as matching entries with snippets; it says nothing about snippet length, result ordering, or truncation behavior for a search tool.

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

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

Two compact sentences with the scope front-loaded and no filler. Every clause carries information an agent can use.

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 rich annotations and no output schema, the description adequately conveys scope and rough return shape (entries with snippets). Pagination semantics for limit/offset remain unexplained, which is a minor 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 60%, so limit, offset, and format are undocumented in both schema and description. The description restates the OS enum values already present in the schema rather than adding query syntax guidance, so it contributes little beyond 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?

States a specific verb (full-text search) and resource (Apple OS/SDK release notes) and enumerates the covered platforms. It is clear what the tool does, though it does not explicitly differentiate itself from overlap-prone siblings such as apple_search_all or apple_doc_lookup.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternative. An agent must infer from the name alone that this is for release-note questions rather than API docs, Swift Evolution, or WWDC 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail — results are merged and ranked by relevance — but says nothing about pagination, the 40-result ceiling, or how ranking ties are resolved.

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 scope statement front-loaded and the merge/ranking behavior following immediately. 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 federated search with no output schema and a largely self-documenting parameter set, the description covers the essentials. It is slightly thin on result handling (pagination/limit) and on when to narrow the search, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 75% and the terse enum values (session, doc, hig, evolution) are decoded by the description into WWDC sessions, Apple docs, HIG, and Swift Evolution, which is real added meaning beyond the schema. The limit parameter and the default type set remain undocumented in prose, keeping this below 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 (Search) and a precisely scoped resource (all indexed Apple content), then enumerates the four covered domains: WWDC sessions, Apple docs, HIG, and Swift Evolution. The word 'all' plus that enumeration clearly separates it from the many domain-specific siblings such as wwdc_search, apple_hig_search, and apple_doc_lookup.

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 by 'at once' and the broad scope; the description never says when to prefer this federated search over the narrower siblings, nor does it mention any exclusions or prerequisites. An agent can infer 'use this for cross-domain lookups' but gets no explicit routing rule.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the source host (docs.swift.org) and the prerequisite discovery step, but says nothing about response size, pagination, or failure behavior for a bad slug.

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 with zero waste; the retrieval purpose is front-loaded and the prerequisite guidance follows. 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?

With only 2 params, full schema coverage, annotations covering safety, and no output schema, the description is nearly sufficient for correct invocation. The only minor gap is not contrasting the markdown vs json formats, which the schema enum already implies.

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 both parameters (chapter slug, format enum with default) are already documented in the schema, including the wwdc_search hint. The description largely restates the schema rather than adding new format/syntax detail, 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?

Specific verb+resource ('Retrieve a chapter from The Swift Programming Language book') plus the content scope it covers (Language Guide and Language Reference). This clearly separates it from general doc tools like apple_doc_get and from the evolution-specific apple_swift_evolution_get sibling.

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: 'Search with wwdc_search first to find the slug,' which is a concrete prerequisite for successful invocation. It stops short of stating when-not to use this tool versus other retrieval siblings, so it is clear context without 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds genuinely useful behavioral context beyond the structured fields by disclosing the response shape ('Returns a markdown table') in the absence of an output schema. It adds nothing about pagination or error behavior, but the annotations carry most of the weight.

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 tightly written sentences with zero filler: the capability and filters come first, then the sibling routing instruction. Every clause earns its place.

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

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

For a seven-parameter read-only search tool with no output schema, the description covers purpose, filters, return format and the alternative tool, which is enough for correct invocation. The only real omission is any guidance on pagination via limit/offset, and the unresolved overlap with apple_swift_evolution_list.

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 71%, so the schema already documents most of the seven parameters, and the description largely echoes those same filter names (version, status, author, keyword). The 'FTS' annotation adds a small hint about keyword matching semantics, but limit/offset/pagination behavior is left entirely to the schema. 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 ('List Swift Evolution proposals') and enumerates the filter dimensions, which is more than a restatement of the title. It explicitly distinguishes itself from apple_swift_evolution_get. However, it does not differentiate itself from the sibling apple_swift_evolution_list, leaving a real ambiguity for an agent choosing between the two list 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?

Gives a clear routing instruction: 'Use apple_swift_evolution_get for the full body of a specific proposal,' which is an explicit when-not-to-use signal plus a named alternative. It stops short of 5 because it never explains when this filter tool is preferable to the sibling apple_swift_evolution_list.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the returned content (status, authors, full body), which no annotation conveys. It says nothing about error behavior for an unknown id, keeping it short of a 5.

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

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

One sentence, front-loaded with the action and resource, with the return payload and id example appended without filler. Every clause 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 return fields (status, authors, full body), which is what an agent most needs for a single-item get. The only gap is the format parameter's effect on the response, which is left 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 50%: format carries its own 'Response format' description while id has none. The description compensates for id by giving the expected identifier form (SE-0428), but adds nothing about the markdown/json format parameter. Baseline 3 fits this partial compensation.

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 (Return) and resource (a proposal by id), plus what the response contains (status, authors, full body) and the id format example SE-0428. It clearly implies the single-item counterpart to apple_swift_evolution_list, though it never names a sibling to disambiguate 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 example id format (SE-0428) signals you must already have a proposal identifier, which indirectly routes browsing users to apple_swift_evolution_list or apple_swift_evolution_filter. There is no explicit when-to-use statement or exclusion for those 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 already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description does not need to restate it. It adds real value by enumerating the valid status values, but it says nothing about pagination behavior (limit/offset) or the shape/format of the response, which are the behaviors not covered by 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?

A single tight sentence with the core action front-loaded and the filter detail parenthesized, so nothing is wasted. It is perhaps too terse to be maximally informative, but the structure is 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 simple read-only list tool whose annotations already carry the safety profile, the description is broadly adequate. The gaps are pagination semantics (limit/offset defaults/caps) and routing among the three closely related swift_evolution siblings, both of which the agent needs to call it well.

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 only 25% (just 'format'), so the schema leaves status, limit, and offset as bare types. The description partially compensates by enumerating the status values (Implemented, Accepted, Rejected, Active review), which the schema does not do, but limit and offset remain undocumented anywhere.

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 clear verb+resource ('List proposals') and scopes the optional status filter, so an agent knows exactly what it returns. However, it never distinguishes itself from its close sibling apple_swift_evolution_filter, which appears designed for the same filtering job, so sibling differentiation is missing.

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?

'optionally filter by status' implies usage context (browse the corpus, narrow by status), which is more than nothing. But there is no when-to-use/when-not guidance, no routing to apple_swift_evolution_get (single proposal) or apple_swift_evolution_filter, leaving the agent to guess which of the three to call.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds that results are synthesized as 'repeated' patterns across source kinds, but says nothing about result volume, ranking, or how the min_source_kinds threshold affects output. Modest added value, not rich.

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 resource and scope front-loaded and no filler. Every clause carries meaning.

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 cross-corpus search tool with no output schema and low schema coverage, the description is thinner than ideal. A caller can understand what the tool does but not enough about filtering, limits, or result shape to invoke it confidently.

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 only 43% across 7 parameters, so the description is expected to compensate and does not. It implies a query and a multi-source scope but never explains limit, platforms, frameworks, year_min, format, or how min_source_kinds controls pattern strength.

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

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

States a specific verb ('Find') and a well-defined resource ('repeated implementation/product patterns') and enumerates the corpora it spans (WWDC, Apple docs, tutorials, HIG, Swift Evolution). This cross-source aggregation distinguishes it from single-corpus siblings like wwdc_search or apple_doc_lookup, though those siblings are not 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?

'Use for API adoption, app architecture, and opportunity discovery' gives implied usage contexts. However, it offers no when-not guidance and does not route the agent away from overlapping tools such as apple_search_all or wwdc_find_api_introduction, leaving the selection decision partly 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 declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds two things annotations cannot: the data comes from a local index and requires prior ingestion, and the payload includes chapter list plus estimated time.

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 filler; the prerequisite is placed early. The parenthetical is slightly compressed/ambiguous but 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, the description usefully names what is returned (chapter list, estimated time) and the ingest prerequisite. However it never explains the required id (format, source) nor the default/format behavior, so an agent still lacks enough to call it confidently from scratch.

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 50% — 'format' is documented ('Response format') but 'id' has no description at all. The description mentions neither parameter, so it does not compensate for the undocumented required 'id' (no hint about its shape or where to obtain one).

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 ('Return a tutorial') and adds scope detail (chapter list, estimated time). It implicitly separates itself from apple_swift_book_get via the word 'tutorial', but never explicitly distinguishes from siblings or states what a tutorial is versus a book.

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 parenthetical '(ingest first)' implies a prerequisite sequence, which is real usage guidance, but it names no ingest tool and gives no when-to-use/when-not-to-use conditions or alternatives. Usage must be inferred.

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

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

Annotations already cover the safety profile (readOnly=true, idempotent=true, destructive=false), so the bar is lower. The description adds genuine context by disclosing the data provenance ('from the deprecated_message field') and that the response concatenates replacement info with WWDC session listings. It does not discuss coverage limits or what happens when no replacement exists.

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 input precondition and names both outputs. Nothing is padding and no sentence fails to earn its place.

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

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

For a read-only lookup with a fully described 2-parameter schema, complete annotations, and no output schema, the description covers what the agent needs: input kind, data source, and return composition. The absence of any note on missing-replacement behavior is a minor 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 both parameters are already documented in the schema, including the enum on 'format' and examples like UIWebView/UIAlertView. The description restates that the input is a deprecated API symbol but adds no syntax or format 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 names a specific verb and resource: given a deprecated symbol, it 'finds what replaced it' and 'lists WWDC sessions introducing the replacement.' That scope is clearly distinct from data-only siblings like apple_api_deprecation and wwdc_find_api_introduction. It loses a point only because it never explicitly contrasts itself 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?

The phrase 'Given a deprecated Apple API symbol' implicitly states the precondition for use, but there is no explicit when-not guidance and no named alternative (e.g. apple_api_deprecation or wwdc_find_api_introduction). Usage is inferable but not routed.

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

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

Annotations already declare the read-only, idempotent, non-destructive, non-open-world profile, so the safety burden is lifted. The description adds a genuinely non-obvious behavioral trait: fuzzy prefix-matching when no exact match exists, which tells the agent it may receive a neighboring section rather than a miss.

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, zero filler. The primary purpose and the accepted inputs lead, and the fallback caveat follows — well front-loaded and appropriately sized for a two-parameter lookup 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?

No output schema exists, so the description carries the return-value burden and does address it ('full text'), plus the format parameter governs markdown vs. json. It doesn't state what happens when neither exact nor prefix matching succeeds, which is the remaining small 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 both parameters (id, format) are already documented in the schema, including the slug/number formats and the enum. The description restates the id forms without adding meaning, and says nothing about the format parameter beyond what the enum provides.

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 and resource ('Retrieve the full text of a specific App Store Review Guideline section') and enumerates the accepted identifier forms (anchor slug vs. section number). This is clearly distinguishable from the sibling appstore_guidelines_search, which would return matching sections rather than one full section.

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 accepted input forms imply usage ('use this when you know the section id'), but no explicit when-to-use guidance or alternative routing to appstore_guidelines_search is given. The prefix-matching fallback note is behavioral rather than usage guidance, so the tool selection guidance remains 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 declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('matching sections with text excerpts') and the scope of the searchable corpus, though it says nothing about ranking or how pagination behaves.

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 what is searched, then what is returned, then when to use it. The parenthetical corpus list earns its place by defining scope, 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 search with no output schema, the description adequately covers corpus scope and return contents. The only real gaps are pagination behavior and result ordering, which are minor for an agent deciding whether and how to call it.

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

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

Schema description coverage is only 50% (query and format documented; limit and offset have no descriptions), and the tool description contributes nothing about any parameter. There is no mention that offset enables paging or that limit caps result count, leaving half the parameters explained only by their names and numeric bounds.

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 across all App Store Review Guidelines sections') and enumerates the corpus (Safety, Performance, Business, Design, Legal), which implicitly contrasts with the singular sibling appstore_guideline_get. It stops short of naming that sibling, so sibling differentiation is inferred rather than explicit.

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

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

Gives clear situational context: 'Use before submitting an app or when auditing for policy compliance.' That tells an agent when the tool is relevant, but there is no guidance on when NOT to use it, e.g. to prefer appstore_guideline_get once a specific section is already known.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, covering the safety profile. The description adds that the bundle is built from *local* data and is 'audit-grade,' which lightly corroborates the offline, repeatable behavior, but it discloses nothing further (e.g. scope of results, cost, determinism of the bundle) 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 tight sentences with the artifact and its inputs front-loaded and the usage timing second. No filler or restated name/title.

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

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

For a 9-parameter, zero-required composite aggregator with no output schema, the description supplies enough to invoke it (what it builds, from which sources, when to use it). It leaves the shape of the returned bundle unstated, but with no output schema and annotations covering safety, that gap is minor.

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 78% and the schema already documents focus, format, feature, symptom, year_min, platforms and frameworks. The description echoes the feature/platform/symptom mapping (matching three params) but adds no new syntax, defaults, or constraints, 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 and artifact ('Build an audit-grade ... research bundle') and names the four data sources it draws from (WWDC, HIG, tutorials, Swift Evolution), which implicitly positions it as the composite aggregator over the granular siblings. It does not explicitly contrast itself against tools like wwdc_search or apple_hig_search, so differentiation stays 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?

'Use before code changes to map feature/platform/symptom to evidence and validation steps' gives a clear triggering context and success intent. No when-not guidance or explicit naming of the alternative single-source tools, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and a closed world, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (ranked posts with title, category, URL, content snippet), which matters because no output schema exists. It does not mention pagination behavior or rate limits, keeping it out of the top band.

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, front-loaded with what and where, then return shape, then use cases. No filler or repetition of the tool name. Slightly more use-case enumeration than strictly needed, but each clause is informative.

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 no output schema, the description covers the corpus, the filterable categories, and the return fields. The notable omission is that the tool is paginated (limit/offset exist) and that offset allows paging past the first result set, which an agent would have to discover from the schema alone.

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 60%, and the schema itself carries the query examples and format enum description. The description does echo the three category values ('Swift Evolution... using-swift... development'), reinforcing the most important filter, but it says nothing about limit/offset pagination or total counts. That is a baseline 3 given partial schema coverage.

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: full-text search across forums.swift.org, and names the concrete content domains (Swift Evolution discussion, using-swift, development). It is clear what the tool does, but it never names the closest sibling (apple_forum_search) or explains how the two corpora differ, so the agent must infer the boundary.

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

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

The final sentence gives implied usage ('finding community discussion around Swift proposals, language behavior, compiler questions, and API usage'), which is genuine context. However, there is no explicit when-to-use versus when-not, and with a near-identical sibling (apple_forum_search) present, the absence of routing guidance is a real gap for retrieval selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds the scope of what is counted, but says nothing about cost, latency, or that counts reflect the live index state. With annotations carrying the behavioral burden, this is adequate but not rich.

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 waste: the first states what is returned, the second states when to use it. The purpose is front-loaded and the examples are compact rather than padding.

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

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

For a one-optional-parameter, no-output-schema tool, the description is nearly sufficient: it tells the agent what is counted, which substitutes for return-value documentation. It could still note that output shape follows the 'format' parameter, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% and the single 'format' parameter carries an enum and default, so the schema fully documents it. The description adds no meaning about the format parameter or how it affects the response, which is the correct baseline-3 case 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 verb and resource: 'Returns row counts for all indexed tables', and clarifies scope with concrete examples (sessions, docs, summaries, cross-reference edges). It does not, however, distinguish itself from the sibling wwdc_ingest_status, which an agent could reasonably confuse with a status/health-check tool.

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

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

'Use to quickly verify the state of the index' gives a clear, actionable when-to-use condition. It stops short of naming alternatives or exclusions — notably wwdc_ingest_status, which likely answers a related question — so the routing guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds that it searches WWDC sessions and returns sessions sorted by year ascending, which is useful output behavior, but does not disclose limitations, rate limits, or auth needs. Comparable to the calibration example 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?

Two sentences, no filler. Front-loads the input and action, then the output ordering. Every sentence earns its place.

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

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

For a simple search tool with 3 parameters and no output schema, the description covers purpose, input examples, and return ordering. The schema provides defaults and an enum, and annotations cover safety. The only gap is the lack of explanation for the limit parameter, which is minor.

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 67% (symbol and format have descriptions; limit has none). The description adds no information about the limit or format parameters and only repeats the symbol examples already present in the schema. It fails to compensate for the undocumented limit parameter, so a low score is warranted.

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 ('searches'), resource ('WWDC sessions'), and goal ('determine which year it was first announced or introduced'). It does not explicitly differentiate from siblings like wwdc_sessions_for_api or apple_api_availability, so it falls 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?

No explicit when-to-use guidance, prerequisites, or alternatives. The description explains function but never says when to choose this over wwdc_search or apple_api_availability. Implied use case exists but no guidance is provided.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description carries a lighter burden. It usefully discloses the composite return shape (ordered steps spanning sessions, tutorials, and docs), which annotations do not cover, but says nothing about error behavior for an unknown id or ordering guarantees.

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 filler. It is efficient, though its brevity is part of why usage and parameter guidance are absent rather than a strength in itself.

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 simple two-parameter read tool with no output schema and complete annotation coverage, the description covers the essential behavior and return content. Only the lack of routing to wwdc_list_pathways for id discovery keeps it from being fully complete.

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

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

Schema description coverage is 50%: the 'format' enum is self-documenting, while 'id' has no description in either schema or prose. The description implies 'id' identifies the pathway but adds no format, source, or discovery hint (e.g. that it comes from wwdc_list_pathways), so it does not fully compensate for the gap.

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 ('Returns a pathway') and adds the scope of what comes with it ('ordered steps: sessions + tutorials + docs'). It implicitly contrasts with the sibling wwdc_list_pathways by being the singular retrieval, but it never names or explicitly distinguishes that sibling.

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 statement of when to use this tool versus wwdc_list_pathways, and no prerequisite or exclusion guidance. The only usage signal is the implicit singular-vs-plural pairing with the list tool, which the agent must infer from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered; the description usefully adds that the payload contains description, topics, transcript, sample-code URLs and related docs. It omits operationally relevant behavior such as the default transcript truncation (transcript_chars default 8000, max 25000) and the default markdown output format.

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 with the key lookup identity front-loaded, and no filler. The second sentence is a content inventory that pulls double duty for parameter semantics, so it earns its place, though it is slightly list-like.

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 name what comes back — and it does. For a read-only retrieval tool whose annotations cover the safety profile, an agent has enough to call it correctly, with the remaining gaps being sibling routing and the truncation/format defaults.

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 only 38% and the description partially compensates: the returned-content list maps implicitly onto include_transcript, include_sample_code and include_related_docs, and the id format is restated. It says nothing about format, transcript_chars, include_chapters or include_judgment, so roughly half the parameters remain unexplained in both places.

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 record for a WWDC session by id' — with a concrete id example (wwdc2024-10150), so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from near-siblings like wwdc_session_summary or wwdc_session_transcript_full, 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?

There is no when-to-use or when-not-to-use guidance, and no routing to alternatives such as wwdc_session_summary for a quick overview or wwdc_session_transcript_full for the complete transcript. The word 'Full' faintly implies 'use when you want everything', but that is inference rather than stated 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds useful context about what is returned (per-source run metadata plus recent additions), but with no output schema it stops short of describing structure, freshness semantics, or what 'last-run' means. Adequate but not rich.

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 no waste; the purpose is front-loaded before the usage hint. Every clause earns its place.

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

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

For a read-only status tool with a simple 3-param schema and annotations covering safety, the description conveys enough to invoke it correctly. Given there is no output schema, a note on the returned fields would have made it fully self-contained.

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 67%: since and format carry descriptions while limit does not. The description references 'most recent sessions added', loosely implying the since/limit scoping, but adds no syntax or default behavior beyond the schema. Baseline for mid-to-high coverage.

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 ('shows') and concrete resources ('per-source last-run metadata', 'most recent sessions added'), so an agent understands it is a status/observation tool. It does not, however, distinguish itself from the similarly-named sibling wwdc_export_status, which the agent could confuse with this one.

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

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

'Use to confirm the index is fresh before querying' gives a clear trigger and even sequences it relative to other calls. There is no explicit exclusion or named alternative, but the when-to-use context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added nuance is provenance ('curated + auto-derived'), which is about content rather than behavior; it says nothing about filtering, ordering, result size, or what a pathway entry contains.

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 front-loaded sentence with no filler, which is structurally clean. But the brevity crosses into under-specification for a tool with two parameters and no output schema, so terseness here costs more than it saves.

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 should at least convey what a returned pathway looks like and how category/format affect the response. Neither is addressed, leaving the agent unable to predict the result shape or filtering behavior before invoking.

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 50%: 'format' is documented by the schema ('Response format' plus an enum), but 'category' has no description anywhere. The tool description does not explain that 'category' filters by topic area or how it relates to the listed examples, so it fails to compensate for the gap.

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 identifies the resource (curated + auto-derived Apple learning pathways) and gives concrete scope examples (SwiftUI, visionOS, Swift 6, AI), which is more than a bare restatement of the title. However, it is a noun phrase with no verb, so the actual action (listing) and the boundary versus the sibling wwdc_get_pathway must be inferred from the tool name rather than the description.

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 when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as wwdc_get_pathway (fetch a single pathway) or wwdc_search. The agent gets no routing signal from the text.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the result is the complete set of linked resources and what forms they take (zips, repos, snippets), but says nothing about the response shape, empty results, or what the format parameter changes.

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 with zero filler, front-loaded on the verb and the returned resource. It is efficient, though arguably too terse to carry its share of the documentation burden for a tool with an undocumented required parameter.

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

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

There is no output schema, and the description does cover the substance of the return value (URLs plus their kinds), which is the main thing needed. Gaps remain on the format parameter, the id contract, and behavior for sessions with no sample code, so it is adequate rather than complete.

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

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

Schema description coverage is 50%: 'format' is documented in-schema with an enum and default, while 'id' has no description. The phrase 'from the session page' implicitly identifies id as a session identifier, which is mild added meaning, but no format, example, or lookup hint is supplied for the one required parameter.

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 (Returns) and resource (every sample-code URL Apple linked from the session page), and enumerates the resource kinds (zips, GitHub repos, snippets). It is clear what the tool does, but it never distinguishes itself from the close siblings wwdc_sample_code_list and wwdc_sample_code_grep, leaving the agent to infer the difference.

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 framing, no exclusions, and no mention of the obvious alternatives. With wwdc_sample_code_list and wwdc_sample_code_grep sitting in the same sibling set, the agent gets no guidance on which of the three to pick for a given intent.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorld=false, and non-destructive, so the safety profile is covered. The description adds a partial view of the return shape (session number, title, duration, transcript/sample-code flags) but says nothing about pagination or result-set size behavior despite limit/offset params.

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 tightly-packed sentences with the primary action and scope front-loaded and no filler. 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 9-param list tool with no output schema, the description usefully sketches the returned fields and the main filter axes. It leaves pagination and sort behavior to the schema, which is acceptable, but a note on result limits would have made it fully self-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 coverage is 78%, so the schema does most of the work. The description echoes the topic, transcript, and sample-code filters but adds no syntax or semantic detail beyond what the schema already documents, and ignores limit/offset/sort entirely.

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 (browse/list) and resource (WWDC sessions) with clear scope (for a given WWDC year), which distinguishes it from wwdc_search and wwdc_get_session. It doesn't explicitly name the sibling it competes with, 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?

Usage is implied — enumerate sessions by year with optional filters — but there is no explicit when-to-use vs when-not-to-use guidance and no named alternative for query-based lookup (e.g. wwdc_search). Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that results are ranked topics with counts, which is mild output context, but says nothing about ordering, truncation at the limit, or default result size.

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 tight sentence with the resource front-loaded and examples parenthetically supplied. Nothing is wasted, though the brevity comes at the cost of the missing usage and parameter 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?

For a simple read-only list tool with annotations covering safety and no output schema, the essentials are present. But with two similar siblings and a half-documented parameter set, an agent still lacks what it needs to invoke this correctly versus wwdc_topics_by_year.

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 only 50% – 'format' is documented in the schema but 'limit' has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented limit (default 20, max 100) or explain how ranking interacts with it.

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 ('Top topics across WWDC sessions') and clarifies the payload includes counts with concrete topic examples. However, it never distinguishes itself from the very similar sibling wwdc_topics_by_year, leaving the agent to infer that this one is the all-years aggregate.

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, no prerequisites, and no alternatives named. The closest sibling, wwdc_topics_by_year, is never mentioned even though an agent must choose between them for a topic-listing request.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description contributes one genuinely useful behavioral detail - that results reflect only what is in the local index - which warns the agent the list may be incomplete relative to all WWDC years. It says nothing about ordering, caching, or how the markdown vs json choice changes output.

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?

One sentence with no filler, and the essential scope qualifier ('in the local index') is placed before the payload detail. Nothing extraneous, though the sentence is arguably thinner than the tool's role warrants.

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 has to describe the return value, and it does: a set of years with per-year session counts. Combined with full schema coverage for the only parameter and annotations covering the safety profile, this is close to complete; only the shape/ordering of the returned set is left unspecified (notably whether counts are returned with the markdown format).

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?

There is a single optional 'format' parameter with 100% schema description coverage and an enum, so the schema fully documents it. The description adds no syntax, default, or format-selection guidance beyond the schema, which is the correct baseline of 3 when structured fields do the work.

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 verb and resource ('Returns the set of WWDC years') and adds scope plus payload detail ('present in the local index with session counts'). That distinguishes it from adjacent discovery tools like wwdc_list_topics and wwdc_list_sessions, though it never names or contrasts those siblings 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?

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent must infer on its own that this is the discovery call to run before filtering by year elsewhere; the phrase 'local index' hints at a scope caveat but does not tell the agent when to reach for 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 already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's added value is disclosing the ranking signals — topic overlap plus full-text similarity on the title. That is genuine behavioral context beyond the structured fields, though it says nothing about result ordering or whether the seed session is excluded.

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, and the mechanism/scope is front-loaded ahead of the use-case examples. 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?

There is no output schema, so the description carries the burden of describing what comes back — it explains how results are selected but not their shape (IDs, titles, snippets) or whether the input session appears in the results. Combined with the undocumented 'limit', the definition is adequate but leaves real gaps for a discovery 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 67% and the description only restates the session_id input, adding no syntax or format guidance. The 'limit' parameter is undocumented in both schema and description (its bounds are merely implied by minimum/maximum), so the description does not compensate for the coverage gap. 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 ('returns related sessions') and pins the input ('Given a session ID'), which alone separates it from the query-string search siblings like wwdc_search. It also names the mechanism (topic overlap plus FTS similarity on the title), so an agent can tell what kind of relatedness it produces without opening the schema.

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

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

Gives clear positive contexts — companion sessions, follow-up content, same framework from a different angle — which maps directly onto the discovery use case. It stops short of explicit exclusions or naming an alternative (e.g. use wwdc_search when you have no seed session ID), so it is context without routing.

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

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

Annotations already cover the full safety profile (read-only, idempotent, non-destructive, closed-world), so the burden is lower. The description adds only that refs are 'indexed' and accepts regex; it says nothing about result shape, pagination, or how limit/format behave.

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 compact sentence with the core filtering behavior front-loaded and an example appended. Efficient, though arguably tight enough that it sacrifices needed detail for a 4-parameter 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 and only 50% parameter coverage, the description should carry more: the is_regex behavior, limit semantics, and return format are all unaddressed. Adequate for a grep-style tool but with clear 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 50%: pattern and format are documented in the schema, while limit and is_regex are not. The description's 'substring/regex' phrasing hints at the is_regex toggle but does not explain the default-off behavior or the limit cap, so it only partially compensates.

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 ('Filter') and resource ('indexed sample-code refs') with the matching mode ('substring/regex') plus concrete examples ('.zip', 'SwiftData'). It clearly differs from a plain list tool, though it never names a sibling to differentiate against.

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 example queries ('find sessions with .zip') imply when the tool is useful, but there is no explicit when-to-use vs wwdc_sample_code_list or wwdc_list_session_code, and no exclusions or prerequisites. Usage is inferable 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description usefully adds the response contract (title, URL, kind, linked session, grouped by year), but says nothing about pagination behavior despite limit/offset params, nor about result size or 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?

Three tight sentences with the purpose front-loaded, followed by return fields and grouping. No filler, though the parenthetical enum listing is slightly redundant with the 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 correctly compensates by naming the returned fields and the grouping, which is the key information for an agent deciding to call it. Only pagination behavior is unaddressed, which is a minor gap for this simple read-only listing tool.

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

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

Schema description coverage is 67%: tag, year, topic and format are documented in the schema, while limit and offset are not. The description reinforces only year/topic filtering and incidentally hints at the tag values ('kind (zip/github/snippet)'), leaving pagination and format semantics to the schema. Baseline 3 is appropriate when the schema does most of the work.

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 all indexed sample code projects') and even enumerates the returned fields and grouping. It is clear and distinct from most siblings, but never names or distinguishes itself from the close sibling wwdc_sample_code_grep or wwdc_list_session_code, so the 'browse all' framing has to carry the differentiation alone.

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

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

The phrase 'optional year and topic filters' implies the browsing use case, but there is no explicit when-to-use or when-not-to-use guidance and no mention of the sibling grep tool that would be preferable for content-based lookup. Usage is inferable 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: retrieval is hybrid FTS + vector reranking when the local embedding model is available, and silently degrades to FTS-only otherwise — a real runtime trait an agent should know.

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 tight sentences with the scope front-loaded, then the return shape, then the fallback behavior. No filler and every sentence 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 13-parameter search with no output schema, the description covers what the tool does, the return form (ranked hits with snippets), and the retrieval-mode caveat. Parameter-level semantics are left to the 77%-covered schema, which is acceptable.

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 77%, so most parameters (year, kinds, limit, detail, format, topics, judgment, platforms, require_transcript) are documented in the schema itself. The description says nothing about any parameter, so it adds no meaning beyond the structured fields; 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 resource (WWDC sessions, Apple docs, tutorials, HIG, Swift Evolution) with the retrieval mode named. It is clear this is a broad multi-corpus search, though it never contrasts itself against the close sibling apple_search_all, leaving the agent to infer the boundary.

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

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

The list of corpora implies the search scope, but there is no explicit when-to-use or when-not-to-use guidance and no alternative named (e.g., wwdc_transcript_search, apple_hig_search, wwdc_list_sessions). 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 declare readOnly/idempotent/non-destructive/closed-world posture, so the safety profile is covered. The description adds genuinely non-derivable context: the response includes a manifest hash for drift detection and prompt-injection handling notes, disclosing the tool's security-relevant 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?

Two tightly packed sentences with zero waste; the return contents are front-loaded and the purpose follows immediately. Every clause 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?

Although there is no output schema, the description enumerates the salient returned fields, so an agent knows what to expect. For a zero-required-param, single-enum-param tool, nothing needed to invoke it correctly is missing.

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

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

Only one parameter (format) with 100% schema coverage and an enum, so the schema fully documents it. The description adds no additional meaning about format selection, which is the baseline-3 case 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 verb (Returns) and enumerates the exact resource contents (tool list, manifest hash, read-only posture, prompt-injection notes, threat-model summary). This is unmistakably distinct from every sibling, which are all content-retrieval or lookup 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?

Explicitly names two use cases: detecting tool-surface drift and reminding agents that retrieved content is untrusted evidence. It gives clear context but names no alternatives or when-not conditions, which is acceptable given no sibling overlaps.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the concrete return artifact — a URL carrying a ?time=SECONDS query — which is the key behavioral detail an agent needs.

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 states the output and its timing behavior with zero filler. Nothing is wasted and nothing redundant with the title beyond the minimum.

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 supplies the return-value shape (URL with time fragment), which is the crucial missing piece. It stops short of explaining how `id`, `timestamp`, or `format` interact, but for a simple read-only link generator this 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 coverage is 50% and the "seconds" parameter has no schema description at all; the description's "?time=SECONDS" is the only explanation of it. However, the required `id` and the `timestamp`/`format` parameters get no clarification in the description, so it only partially compensates.

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 ("returns a URL") with a clear resource and effect (deep link into a session at a given time). An agent can tell it apart from generic session retrieval siblings, but it never explicitly names any of the 40+ siblings it must be chosen over.

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 "so the user jumps straight to a chapter," which conveys the linking-at-a-timestamp scenario, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative (e.g. wwdc_get_session).

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description usefully adds that results are relevance-ranked and that year is shown prominently, but says nothing about result limits, pagination, or transcript-snippet 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?

Three compact sentences that are front-loaded with the core action and scope. Every sentence earns its place with 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 search with no output schema, the description conveys the search fields, ranking, and year emphasis, which is close to complete. It stops short of describing result shape or limits, a minor gap for a lookup tool with full annotation 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 all four parameters (including year, format, include_transcript) are documented in the schema. The description adds no parameter-level detail beyond the schema and only obliquely touches search scope, 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 (find), resource (WWDC sessions), and the exact search scope (title, description, or transcript) tied to an API symbol. This distinguishes it from transcript-only siblings like wwdc_transcript_search and generic wwdc_search without needing to open any 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 symbol-in-sessions framing implies when to use it, but no alternatives (e.g., wwdc_search, wwdc_find_api_introduction) or exclusion conditions are named. Usage is inferable but not 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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real value by disclosing the degradation path ('falls back to the session description if no summary has been generated yet') and the ingest step needed to populate summaries — non-obvious behavior an agent should know before trusting the output.

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 tight sentences, front-loaded with the return payload, followed by the fallback condition and the population command. No filler or restatement of the name.

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 enumerates the returned fields and explains the fallback shape, which is exactly what an agent needs. Two parameters, one required, both documented in the schema; nothing material is missing.

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

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

Schema description coverage is 100%, including the session_id format example and the enum for format, so the schema does the heavy lifting. The description adds no parameter-level detail (e.g., what the format enum changes in the response), 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 ('Returns the AI-generated structured summary for a WWDC session') and enumerates the payload (overview, key APIs, topics, code patterns, difficulty level). This clearly separates it from wwdc_get_session, which returns the raw session record rather than the derived summary.

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 mention of a fallback to the session description hints at what happens when data is absent, and the ingest command hints at population prerequisites. There is no explicit statement of when to pick this over wwdc_get_session or wwdc_session_transcript_full.

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 read-only, idempotent, non-destructive, closed-world semantics, so the lower bar applies. The description adds genuinely useful behavioral context: the transcript arrives in bounded chunks and iteration terminates at totalChunks, which is not encoded in 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, zero filler, with the core purpose and the paging loop front-loaded and the alternative-tool note last. Every sentence carries distinct information.

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

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

No output schema exists, but the description implies the response includes a totalChunks field and usable text chunks, and it covers the paging loop an agent must drive. A brief note on what each chunk contains or the format trade-off would make it fully self-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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining how chunk_index is driven (start at 0, increment, compare against totalChunks), turning an isolated parameter into a paging protocol an agent can execute.

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 the complete transcript of a WWDC session') plus the delivery mechanism ('in paginated chunks'). It also contrasts itself against the sibling wwdc_get_session by framing itself as the full-transcript option versus that tool's excerpt.

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 usage protocol ('Use chunk_index=0 to start, then increment until chunk_index >= totalChunks') and a clear condition selecting this tool over wwdc_get_session. It stops short of stating exclusions (e.g. when to prefer wwdc_transcript_search for targeted lookups).

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description usefully adds matching semantics ('case-insensitive substring match against the speakers field'), which is not derivable from the annotations, but says nothing about result ordering, pagination, or behavior when no speaker matches.

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 capability front-loaded and the matching rule immediately after. No filler or restatement of the title.

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 simple read-only search tool with a well-described 4-param schema, the definition covers what the tool does and how matching works. No output schema exists, so return shape is unstated, but this is a minor gap for a filtered-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 75%, with the speaker parameter already documenting partial-name matching via an example. The description's substring note is mildly reinforcing rather than additive, and it says nothing about year, limit, or format beyond what the schema states.

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: 'Find all WWDC sessions featuring a speaker.' This is clearly distinguishable from siblings like wwdc_search (general session search) and wwdc_transcript_search (transcript full-text), so an agent can route without opening schemas.

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 tool name and the speaker-scoped purpose, but there is no explicit when-to-use guidance or naming of alternatives such as wwdc_search or apple_forum_search for speaker-related lookups. Adequate but leaves the agent to infer the boundary.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the dual-mode behavior (omit year for a cross-year table), which is genuinely useful beyond the annotations, but says nothing about result size, ranking method, or ordering.

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 short sentences, front-loaded with the core capability before the example use cases. Every clause carries information; nothing is padded, though the quoted example queries are somewhat redundant with the usage statement that precedes them.

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

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

No output schema exists, so the description must convey enough about returns, and it only gestures at this via 'cross-year comparison table'. An agent knows the modes but not the response shape (ranked list with counts?) or whether markdown/json formats are actually rendered tables. Adequate but with a visible gap for a no-output-schema 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% – year, limit, and format are all documented in the schema, including 'omit for a cross-year comparison table' and the default/max on limit. The description only restates the year omission behavior in prose, adding no new parameter semantics. 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 (Show) and resource (most popular WWDC session topics), plus the two modes: single-year rankings and a cross-year comparison table. It is distinguishable from the nearby wwdc_list_topics sibling via the popularity/trend angle, though it never names that sibling to sharpen the contrast.

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?

Concrete example queries ('what was hot at WWDC 2024?', 'comparing topic frequency trends') make the intended use clear. It lacks any when-not guidance or an explicit pointer to alternative tools such as wwdc_list_topics or wwdc_search, so it stops short of full routing 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the FTS5 backend and the snippet-in-context return format, which is useful, but omits query-syntax behavior (phrase quoting, boolean operators) that materially affects results for a full-text tool.

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

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

Two sentences, zero filler, and the core action plus its scope are front-loaded before the return-value note. Nothing could be cut without losing 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 7 parameters, no output schema, and a full-text backend, the description is adequate but thin. It doesn't explain FTS5 query syntax (which drives match behavior), pagination via limit/offset, or how the overlapping year filters relate; the annotations carry the safety profile but not the search semantics.

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 71%, so the schema already documents most parameters (year bounds, limit, offset, format). The description contributes only the notion that the query is a free-text phrase against an FTS5 index; it adds no syntax detail, no note on how year/year_min/year_max interact, and nothing on limit/offset.

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 resource (full text of indexed WWDC transcripts), and the return shape (matching sessions with a snippet). It is distinguishable from retrieval-oriented siblings like wwdc_session_transcript_full, but it never names or contrasts them 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?

The description implies when the tool applies (finding sessions by phrase) but gives no explicit when-to-use guidance, no exclusions, and no routing toward alternatives such as wwdc_search or wwdc_session_transcript_full. An agent must infer selection from the name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only that sessions are returned per year so the agent can see what was added — modest value beyond what annotations provide, with no mention of result ordering, empty-year handling, or truncation via limit.

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

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

Two sentences, zero filler, with the purpose stated first and the illustrative use case immediately after. Nothing is redundant and the reader learns the scope in the first clause.

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 five-parameter tool with full schema coverage and no output schema, the description does the one thing it must: it says the response contains sessions for each year, so the agent knows the return shape. Only minor gaps remain, such as how year_a/year_b ordering is enforced and what happens when a year has no matching sessions.

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, including the enum format and the limit bounds, are already documented. The description's 'framework, feature, or API area' phrasing for topic repeats the schema's own wording rather than adding format or syntax detail beyond it, 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 (compares) and a specific resource (WWDC session coverage of a topic) with an explicit two-year scope. The cross-year comparison framing is inherently distinguishable from siblings like wwdc_topics_by_year or wwdc_search, which operate on a single year or a query.

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 quoted example question ('What's new in SwiftUI between 2024 and 2025?') implies when the tool is appropriate, which is useful context. However, it never names an alternative (e.g. wwdc_topics_by_year for single-year coverage, or wwdc_search for topic lookup) or states when not to use it, leaving routing to inference.

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