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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only analysis action through the verb 'Produce' and states it returns an overview and summary counts, which is transparent about its non-mutating nature. However, it doesn't explicitly mention that it does not modify the project or any potential prerequisites, but the intent is clear.

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

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

The description is concise yet informative, front-loading the purpose and then adding usage guidance. Every sentence earns its place without redundancy. The structure flows from 'what it does' to 'when to use it', making it easy for an agent to parse quickly.

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

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

The description provides sufficient context for an agent to know when to call the tool and what to expect in return. It lists the categories of findings and the usage strategy. While it doesn't detail the exact output format, there is no output schema, and the description gives enough for an agent to make an informed call. It could mention potential performance implications or prerequisites, but for a relatively simple overview tool, this is adequate.

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

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

The schema covers the single 'path' parameter at 100%, describing it as an absolute path to the project root. The description does not add any additional meaning or usage details about this parameter, relying entirely on the schema. Given the high schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with specific deliverables (file/line counts, deployment target, Swift tools version, frameworks, test existence) and a summary of findings across named rule categories. It distinguishes itself from the focused sibling tools by framing itself as an initial overview 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?

The description explicitly instructs to use this tool first when unfamiliar with a codebase, and then to run focused tools on categories with findings. This directly contrasts with the sibling review tools, providing clear guidance on when to use this vs. alternatives.

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

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

With no annotations, the description carries the full behavioral burden and discharges most of it by listing the exact checks performed. It implies a non-mutating audit but does not explicitly state whether files are modified or how findings are returned, which is a minor gap.

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 compact sentence enumerates all checks in a structured colon list, and a second sentence provides the usage trigger. There is no filler, repetition of schema content, or unnecessary 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 one-parameter audit tool, the description covers what it checks and when to use it. It does not describe the shape of the returned report, but the simple input and absent output schema make this a minor omission rather than a blocking gap.

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

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

Schema description coverage is 100%, so the schema already defines 'path' as an absolute path to the Swift project root. The description adds no parameter-level detail, but none is needed for this single, self-explanatory 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 action ('Check a Swift project') and enumerates concrete issue categories: Info.plist purpose strings, PrivacyInfo.xcprivacy, localization, accessibility labels, and print() logging. This clearly distinguishes it from sibling review tools focused on code quality, concurrency, security, or architecture.

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

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

Explicitly says 'Use before submitting to App Review,' giving a clear trigger condition. It does not name alternatives or exclusion cases, but the sibling tool set makes the boundary reasonably inferable.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states the core action and workflow placement, but does not mention build outputs, side effects, or failure behavior. This is a reasonable baseline for a straightforward build command, but it leaves some behavioral detail undisclosed.

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

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

The description is two concise sentences with no wasted words. It front-loads the action, then provides workflow context and prerequisites. 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?

The tool has six parameters, no annotations, and no output schema, but the description only covers scheme and the project/workspace relationship. It omits guidance for destination, configuration, and derivedDataPath, and does not describe what the build returns or how failures are reported, leaving an agent under-informed for non-default invocations.

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 0%, so the description must compensate for undocumented parameters. It clarifies that scheme is required and that project and workspace are alternatives, but it does not explain destination, configuration, or derivedDataPath, leaving half the parameters semantically uncovered.

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

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

The description states a specific verb and resource: 'Run xcodebuild build for a project or workspace.' It clearly identifies the build action and differentiates it from sibling tools like install_app and launch_app by positioning it as the step before installing and launching.

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

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

It gives clear context on when to use the tool: 'Use before installing and launching the app.' It also states the key prerequisite of requiring a scheme and either a project or workspace, though it does not explicitly name alternatives or exclusion conditions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains what the tool catches (missing guards, over-restrictive guards, missing runtime availability checks) and the consequence of the bug it detects (silently dropping iOS 26 devices to fallback). It doesn't state whether the tool modifies code or only reports findings, but the verb 'Verify' and 'Catches' imply a read-only analysis, which is reasonably transparent.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second gives a concrete example, and the third adds usage timing. Every sentence earns its place, and there is no redundant restating of the tool name or 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 single-parameter analysis tool with an output schema present, the description covers the key context: what it checks, why it matters, and when to use it. It doesn't detail the output format, but the output schema exists and the description needn't explain return values. The only minor gap is not stating whether it performs read-only analysis, but 'Verify' and 'Catches' strongly imply that.

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

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

Schema description coverage is 100%, so the schema already documents the single 'path' parameter. The description adds context by implying the path is a Swift project root, but it doesn't add meaning beyond the schema's own description. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('Verify') and resource ('version-gated Apple APIs'), and clearly distinguishes the tool's purpose from siblings like review_swift_concurrency or audit_app_store_readiness by focusing on guard placement relative to the introduced version. It also names concrete examples (Liquid Glass iOS 26 vs 27) that make the purpose unmistakable.

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

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

The description explicitly says 'Use before shipping, or after bumping an SDK,' which gives clear timing context. It also contrasts with alternatives implicitly by naming what it checks (availability guards and Foundation Models runtime checks), and the sibling list shows other review tools exist, making this guidance valuable for 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?

With no annotations provided, the description carries the behavioral burden. It usefully discloses that this WRITES a NEW project and deliberately does not implement the full idea. However, it does not mention side effects, whether an existing directory would be overwritten, required permissions, or what the response/output contains, so some behavioral ambiguity remains.

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

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

Two sentences with no filler. The core action and scope are front-loaded, and the follow-up workflow direction is useful rather than redundant. 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?

The description gives enough context to select and invoke the tool correctly, especially by clarifying the starter-only scope and pointing to subsequent steps. Still, without an output schema or annotations, an agent is left guessing about return values, generated file structure, and failure behavior—gaps that matter for a project-generation 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 only 25%, so the description must compensate. It adds meaning by referencing the implementation brief and optional XcodeGen specification/icon layers, which map to the 'brief' and 'xcodegen' parameters. However, it does not clarify the expected format of 'name' or 'brief' beyond what the schema already provides, leaving part of the parameter semantics implicit.

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 ('Create') and clear resources: an editable Swift app starter, an implementation brief, and optional XcodeGen/icon layers. It also explicitly scopes the tool by stating it does NOT implement the full app idea, which distinguishes it from planning or implementation tools.

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

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

The description gives a clear workflow context: create the starter project first, then use source retrieval, review, and simulator tools to implement and verify. It does not name specific sibling alternatives or exclusions, but the 'does not implement the full app idea' statement provides enough guidance for when to stop using 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 communicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by stating that the default response is a compact overview with local source routes, and that full mode returns the entire guide and API topic map. No contradiction 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 short sentences with no filler. The default behavior is front-loaded, and the conditional guidance for full view is stated directly. 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 read-only tool, the description covers the major output modes and safety profile via annotations. However, with no output schema and no parameter descriptions, the required id is left unexplained, and phrases like 'local source routes' remain ambiguous enough that an agent may not know exactly what to expect or provide.

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 0%, so the description must compensate. It provides some meaning for the view parameter by contrasting overview with full, but the required id parameter is completely undocumented in both the schema and description. An agent does not know what id values are valid or how to obtain them (e.g., from search_apple_technologies).

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

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

The description states a specific verb and resource: get a compact technology overview and local source routes from an Apple technology guide. It is clear and adds the default-vs-full distinction, but it does not explicitly differentiate this tool from the closely related search_apple_technologies 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?

The description gives useful conditional guidance: 'Use view full only when the entire guide and API topic map are required.' However, it does not say when to choose this tool over search_apple_technologies, get_apple_updates, or local reference tools, leaving the tool-selection context implied rather than explicit.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds a useful caveat that results are not claimed to be live, and it indicates that pages will be dated with version-specific source links, giving extra behavioral context beyond the structured 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 short, front-loaded sentences with no filler. The core operation is stated first, and the 'Does not claim live results' caveat earns its place as an important behavioral note.

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

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

The description conveys what the tool searches and partially describes the result type, but with no output schema it leaves the output format and query semantics unexplained. It is adequate for a simple search tool but has clear gaps an agent would need to infer.

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 0%, and the description does not explain what the 'query' parameter should contain or how the 'limit' parameter behaves. While 'limit' has useful bounds in the schema, the meaning of 'query' and its relationship to results are left entirely to inference.

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 ('Search') and a specific resource ('dated Apple update and release-note landing pages with version-specific source links'), making the tool's purpose unambiguous. It also distinguishes this tool from sibling search tools like search_apple_technologies by focusing on updates and release notes.

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

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

The description provides clear context for when to use the tool: when looking for Apple update and release-note landing pages. It does not explicitly name alternatives or exclusions, but the resource is specific enough that an agent can select this tool appropriately.

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 behavioral detail: it returns heading offsets (not full content). This clarifies what the tool produces without contradicting annotations. However, it does not describe the format or granularity of offsets, which is a minor gap given the annotations cover the key safety traits.

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

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

The description is a single sentence with zero waste. The core action ('Get heading offsets') is front-loaded, and the purpose is stated efficiently. Every word 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 tool with one parameter and no output schema, the description is moderately complete: it tells what it does and why. However, it does not describe the structure of the returned offsets (e.g., list of sections, byte ranges, line numbers) or the exact input format for 'path'. Since there is no output schema, this gap is notable, though the tool's simplicity and the read-only annotations mitigate the impact.

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

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

The schema has one parameter, 'path', with only length constraints and no description (0% coverage). The tool description does not clarify what 'path' refers to (e.g., a local file path, a reference identifier, or a URL). The title 'Outline a local guide' hints at the resource type, but the description does not explain the expected format or semantics of 'path'. With zero schema coverage, the description should compensate, and it does not.

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

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

The description states a specific verb ('Get'), a resource ('heading offsets'), and a clear purpose ('so only the relevant section needs to be read'). This distinguishes it from sibling tools like read_local_reference, which would retrieve full content, and search_local_references, which would search. The purpose is immediately clear.

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 to use it ('so only the relevant section needs to be read'), but it does not explicitly name alternatives or exclusions. It leaves the agent to infer that this should be used before reading a long local reference, but it does not reference sibling tools or state when not to use it. This is adequate 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description reveals that it relies on xcrun simctl install but does not disclose potential side effects (e.g., replacing an existing app, requiring the simulator to be booted). It also doesn't mention whether it automatically boots a simulator or if the user must ensure it's running. This is a moderate gap for a state-changing operation.

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

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

The description is two sentences long, front-loaded with the core purpose, and directly states the use context. Every sentence contributes useful information without fluff. Excellent conciseness.

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

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

The tool is a two-parameter, straightforward installation routine with no output schema. The description covers the main context (after build or locating bundle) and the mechanism. It could benefit from noting prerequisites like simulator being booted, but given the simplicity and the clear schema, it is nearly 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?

The input schema already provides 100% coverage of both parameters, so the baseline is 3. The description adds minimal extra value about the parameters (though it does mention 'after locating a derived-data app bundle' which hints at the appPath). However, it does not clarify the format of the UDID beyond the UUID format in the schema. Given the schema is strong, the description's limited addition is acceptable; a 4 is fair.

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

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

The description clearly states the specific verb (Install), the resource (.app bundle), and the mechanism (xcrun simctl install). It explicitly mentions the target context (simulator) and differentiates from sibling tools that launch, terminate, or build apps.

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

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

The description provides clear when-to-use guidance (after build_project or after locating a derived-data app bundle). It does not explicitly exclude alternatives, but the sibling list includes launch_app and terminate_app, and the description does not confuse install with those. It lacks an explicit 'do not use for' statement but is otherwise sufficiently contextual.

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

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

With no annotations, the description must carry behavioral disclosure. It accurately conveys that launching starts an app and that args are forwarded after the bundle id, but it does not describe return behavior, failure modes, or prerequisites such as the simulator being booted. This is useful but incomplete.

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 focused sentences, with the core action front-loaded and the optional-argument detail in the second sentence. No filler or repetition.

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

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

For a simple launch tool the essentials are present: what to launch, how to identify it, and how to pass extra args. However, with no output schema and no annotations, an agent is left without information about return values or failure conditions, and the need for a booted simulator is only implicit. Slightly more context would make it 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?

The schema documents udid but leaves bundleId undocumented, and only 33% of properties have descriptions. The description compensates by explaining that the target is identified by bundle identifier and that args are appended after the bundle id, adding meaning to two of the three 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?

The description states 'Launch an installed app in the simulator by bundle identifier,' giving a specific verb, resource, and mechanism. This clearly differentiates it from sibling tools like install_app, simulator_boot, and terminate_app, so an agent can select it without opening the schema.

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

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

The phrase 'installed app' implies the prerequisite that the app must already be present, and the note that optional arguments are 'useful for UI-test/debug launch flags' gives a concrete use case. It does not explicitly name alternatives or state when not to use it, so it falls 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?

No annotations are provided, so the description carries the full burden. It lists detailed validation checks, which conveys what the tool inspects, but it does not explicitly state that the operation is read-only/non-destructive, nor does it describe the output format (e.g., returns a list of issues). For a validation tool, this is a moderate gap—'validate' implies read-only, but the agent is left to infer side effects and result structure.

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

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

The description is a single well-structured paragraph that front-loads the core purpose and then lists specifics in a clear, colon-delimited enumeration. It is somewhat long but every detail adds value; there is no fluff or repetition.

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

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

The tool has no output schema, so the description should explain what the agent will receive (e.g., a report, exit code). It does not mention the return value or outcome. It also does not explicitly state prerequisites beyond the path, though the path is defined. Given the detailed list of checks, it is mostly complete, but missing output/result information is a notable gap.

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

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

Schema coverage is 100%, with the single 'path' parameter well-described in the schema as 'Absolute path to the skill repository root (the folder containing SKILL.md).' The description adds no additional parameter-specific semantics beyond what the schema already provides, 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 clearly states the tool validates an Agent Skill repository's metadata, not Swift source, and enumerates specific checks (SKILL.md frontmatter, subagent definitions, mirror file drift, doc paths). It explicitly distinguishes from sibling tools like review_swift_* by saying 'rather than Swift source', making its purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use when authoring or reviewing a skill, before publishing a release, or when a subagent or skill is not being invoked as expected.' It also implicitly excludes Swift source, helping an agent choose this tool over Swift-review siblings. This is a clear when-to-use statement.

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

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

With no annotations, the description carries the full burden. It discloses the mechanism (`xcrun simctl openurl`) and primary effect, but it omits important behavioral context such as requiring a booted simulator, possible side effects on app state, and what happens on failure. This is adequate but not fully transparent.

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, no filler, and the core action is front-loaded. Every sentence contributes either the operational mechanism or the intended use cases.

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 tool, the description covers the operation, mechanism, and common use cases. It lacks explicit notes about the simulator needing to be booted and does not describe the return/error behavior, but the schema handles the UDID prerequisite guidance. Overall, this is sufficient for a competent agent to use it correctly in most cases.

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%, and the `url` parameter has no schema description and only a `uri` format. The tool description adds meaning by framing the URL as a deep link, universal link, or onboarding route, which clarifies the expected value. The `udid` parameter is already well described in the schema with guidance to use `simulator_list`.

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

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

The description names the specific action ('Open a URL in the simulator'), identifies the underlying command (`xcrun simctl openurl`), and lists concrete verification scenarios. It is clearly distinct from siblings like `launch_app` because it targets URL/deep-link opening rather than plain app launching.

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

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

The description explicitly states when to use the tool: 'Use to verify deep links, universal links, onboarding routes, and state restoration.' It does not mention exclusions or alternatives, so it falls just short of a 5, but the intended context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral trait: it returns a specification, not a native .icon document, which is helpful. However, it doesn't detail the return format (e.g., JSON structure) or any constraints like max concept length, which the schema already covers.

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

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

The description is two sentences, concise and front-loaded with the primary purpose. The second sentence clarifies a limitation without extra fluff. Every word 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?

Given the tool's simplicity (2 params, no output schema), the description is nearly complete. It tells the agent what to expect (a specification) and what it doesn't do (fabricate a native icon). It could be more complete by specifying the structure of the specification, but the absence of an output schema reduces that need. Siblings don't require explicit differentiation.

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 0%, and the description goes beyond the schema by clarifying the tool's output (specification vs binary) and the nature of the parameters: 'appName' and 'concept' are self-explanatory, but the description adds that the tool does not fabricate a native document, implying the concept is used for planning. With 2 params and minimal schema info, the description compensates well.

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

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

The description states a specific verb ('Return') and resource ('separate-layer icon specification'), clearly indicating the tool produces a specification rather than a binary icon file. It distinguishes itself from siblings by focusing on layered icon composition, which is not evident from sibling names. However, it doesn't explicitly compare to a sibling like 'plan_ios_app' that might also plan artwork.

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 it is for planning an app icon, but does not explicitly state when to use it versus alternatives like 'create_app' or 'plan_ios_app'. It lacks guidance on prerequisites (e.g., need for an app concept) or exclusions (e.g., not for generating final assets). The context is clear enough for an agent to infer usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower; the description adds concrete side-effect context with 'No files are created and no build is claimed.' This clarifies what the tool will not do, which is valuable beyond the annotation flags. There is no contradiction between the description and annotations.

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

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

The description is two tight sentences with the core action and deliverable front-loaded. The second sentence earns its place by removing ambiguity about side effects. There is no filler or redundant 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 read-only planning tool with no output schema, the description gives a high-level return type and non-effects, which is helpful but incomplete. It does not describe the shape or structure of the returned workflow/argument array, provide parameter-level guidance, or distinguish itself from closely related siblings like plan_app_icon. An agent could call it successfully with name and brief, but would be uncertain about the exact output contract.

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 0%, so the description must compensate for the undocumented name and brief parameters; it only partially does so by referencing 'a named app' and the title's 'brief.' It does not explain what constitutes a valid brief, how name is used in planning, or how the two parameters interact. This leaves significant semantic ambiguity for an agent.

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 deliverable: 'Return an implementation workflow and safe CLI argument array for a named app.' The title 'Plan an iOS app from a brief' reinforces the resource and purpose. It also separates itself from siblings like build_project and create_app by explicitly disclaiming file creation and build claims.

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 intended use is implied: the tool plans an iOS app from a brief and produces a workflow plus CLI args, which suggests use before implementation. However, it does not explicitly say when to prefer this over related siblings such as create_app, build_project, or plan_app_icon, nor does it provide exclusions or alternative routing. The context is clear enough but the comparative guidance is missing.

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

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

The description goes well beyond the annotations. It discloses that the operation is fully local, makes no network requests or submissions, requires user approval for any link opening or submission, and that GitHub sign-in is needed only for the later submit step. It also adds the anti-repetition rule ('Do not repeatedly suggest a report after dismissal'), which is behavioral guidance not available in annotations. All disclosed behaviors align with readOnlyHint, idempotentHint, and destructiveHint=false.

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?

Five dense sentences, each carrying distinct information: scope, constraints, network behavior, approval requirement, and repetition policy. The most important scoping ('LOCAL... not a defect in the user app') is front-loaded. No redundant phrasing or boilerplate.

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

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

For a tool with 5 enum-constrained parameters and no output schema, the description covers the full call lifecycle: what it produces (a local preview), how to present it (show complete preview to user), what not to include, when submission may happen, and the social rule about not nagging. Combined with the annotations (read-only, idempotent, non-destructive), an agent has everything needed to invoke it correctly and set user expectations.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It states that only fixed categories are accepted and explicitly forbids source, logs, paths, and credentials, which helps clarify the enum-constrained parameters. However, it does not map the description to individual parameters (feature, symptom, client, platform, reproducibility), relying on the self-descriptive enum values. This is adequate but not fully compensating for the zero 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?

The description uses a specific verb and resource: 'Prepare a LOCAL issue preview for an ios-agent-mcp failure.' It explicitly scopes the tool to failures of the agent itself, not user app defects, and distinguishes it from the development-oriented sibling tools by its reporting purpose. The uniqueness is obvious even without comparing 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?

Provides clear context: use for ios-agent-mcp failures, not user app defects; never include source, logs, paths, or credentials; only suggests after user approval; don't repeat after dismissal. It does not name specific sibling alternatives, but the tool's reporting role is so distinct from the other tools that explicit exclusions are less necessary. The 'not a defect in the user app' line effectively routes away from the app-review 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'Use nextOffset to continue without omission' discloses pagination behavior, and 'Offset is a JavaScript UTF-16 string index' discloses a subtle technical detail that could trip up agents. It doesn't describe error cases, but the annotations carry the safety burden.

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, zero filler. The core action and scope are front-loaded, the pagination contract is stated, and the technical offset detail is included. 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 read tool with strong annotations (readOnly, idempotent, non-destructive), the description covers the essential behavioral contract: bounded ranges, pagination via nextOffset, no network/filesystem access, and the UTF-16 offset semantics. It doesn't mention what happens on invalid paths or whether the output schema includes nextOffset, but the pagination hint implies it. Given the tool's simplicity, this is nearly 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 0%, so the description must compensate. It does: it explains the meaning of offset ('JavaScript UTF-16 string index') and the pagination contract ('Use nextOffset to continue without omission'). It doesn't explicitly explain maxChars, but the name is self-explanatory and the schema bounds it. The description adds real meaning beyond the raw schema.

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

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

The description states a specific verb ('Read'), a specific resource ('exact bundled file content'), and a precise scope ('bounded character ranges'). It also distinguishes itself from siblings by explicitly noting 'no network or user filesystem access', which separates it from search_local_references and get_reference_outline.

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 clearly implies when to use this tool: when you need exact bundled file content in bounded ranges, and explicitly says what it does NOT do ('no network or user filesystem access'). It doesn't name alternative siblings explicitly, but the exclusion of network/filesystem access plus the 'bundled file' scope gives clear context. It could be improved by naming search_local_references as the alternative for searching, but the guidance is still strong.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description warns that findings are 'heuristic advisories, not blanket deprecations or proof of invalid code,' which prevents an agent from treating the output as definitive. It also notes that Apple Intelligence review only happens when explicitly requested, matching the appleIntelligence flag in the schema.

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

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

Two sentences deliver the full scope, conditional behaviors, caveats, and use context with no filler. The caveat about advisory findings is front-loaded and prevents misinterpretation.

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 annotations confirming read-only behavior)Skip and an output schema covering return structure, the description provides everything an agent needs: target domain, optional scopes, when to use it, and how to interpret findings. Nothing critical is missing.

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

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

Schema description coverage is 100%, and each parameter already has a clear description in the schema. The tool description adds useful domain framing but no additional parameter-specific semantics, so the schema carries the semantic load.

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

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

The description names a specific resource (SiriKit/INIntent to App Intents migration opportunities) and the extended optional scopes (Apple Intelligence entity schemas, onscreen entity associations). It clearly separates this from sibling Swift/architecture review tools and reinforces the domain with 'Use when integrating Siri, Shortcuts or Apple Intelligence.'

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

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

It gives clear when-to-use guidance ('Use when integrating Siri, Shortcuts or Apple Intelligence') and conditional triggers for the optional scopes ('when explicitly requested'). It does not name sibling alternatives or explicitly say when not to use it, so it lacks the full when/when-not routing of a top-tier definition.

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

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

With no annotations provided, the description carries the full burden and does well by listing six specific defect patterns the tool detects. However, it does not explicitly state whether the operation is read-only, whether a build is required, or how results are returned; the existing output schema partially covers the result 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?

The description is two sentences with no filler, but the first sentence is a dense, long enumeration of defects. The colon-delimited list makes it scannable and the usage guidance is front-loaded at the end, so it remains 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 tool with one parameter and an output schema, the description covers what it checks, when to use it, and the meaning of the project path. It could add explicit sibling differentiation or exclusions, but an agent has enough to select and invoke it correctly.

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

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

The sole parameter 'path' has 100% schema description coverage, so the schema already documents the meaning. The description's phrase 'Swift project root' largely mirrors the schema and adds no format, example, or edge-case guidance beyond 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?

The description states a specific verb ('Check') and resource ('a Swift project') and enumerates concrete defect categories, such as live default dependencies, presentation-layer naming of concrete data-layer types, singletons in view models, and UI framework imports. This level of specificity clearly differentiates it from sibling review tools like review_swiftui or review_swift_concurrency.

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

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

The description explicitly provides two trigger conditions: use when reviewing MVVM or Clean Architecture code, or when a screen cannot be previewed without a network. It does not explicitly mention when not to use it or name alternative tools, which keeps it from 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the exact checks performed, including @Observable isolation, Task.detached, DispatchQueue.main.async in async code, @unchecked Sendable, nonisolated(unsafe), unstructured Tasks, empty catch blocks, and Task shadowing. This is substantive behavioral detail, though it does not explicitly state side-effect-free behavior or limitations.

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

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

The description is front-loaded with the primary action and resource, followed by a compact comma-separated list of specific checks, and ends with concrete use cases. Every sentence and list item adds information; there is no fluff.

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

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

The description covers what the tool checks protector and when to use it, and the output schema exists to define the return shape. Given a single path parameter and high schema coverage, the description is complete enough for an agent to select and invoke the tool correctly, though it could optionally clarify that the analysis is non-mutating.

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

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

Schema coverage is 100%, and the schema description for 'path' already specifies it as an absolute path to the Swift project root containing Package.swift or .xcodeproj. The tool description adds no additional parameter-level nuance, so baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair, 'Check a Swift project for Swift 6 concurrency and isolation defects,' and then enumerates concrete defect categories. This clearly distinguishes it from sibling review_swift_* tools that target architecture, memory, security, performance, testing, and SwiftUI.

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

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

The description explicitly states when to use the tool: 'reviewing Swift code, migrating to Swift 6, or diagnosing a data race.' It does not explicitly name alternatives or exclusions, but the domain-specific defect list and use cases give a clear selection context relative to sibling tools.

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

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

With no annotations provided, the description carries the full burden. It is transparent about what the tool analyzes, listing concrete detection targets. The verb "Check" implies a read-only analysis, but the description does not explicitly confirm no side effects, which is a minor gap.

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

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

The description is a single, dense sentence with every clause providing concrete detection categories or usage guidance. It is front-loaded with the core purpose and contains no filler or redundant phrases.

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

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

For a single-parameter analysis tool with an output schema, the description covers the tool's purpose, the specific patterns it detects, and the signals for when to run it. Nothing necessary for an agent to decide to invoke it 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?

The schema already describes the single `path` parameter with 100% coverage, including the meaning of the project root. The description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Check a Swift project for retain cycles and lifetime defects." It then enumerates the exact defect categories, which clearly differentiates this from sibling review tools like review_swift_concurrency or review_swift_performance.

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

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

The description explicitly states when to use the tool: "when memory grows over time, when deinit is never called, or before shipping a screen with timers or subscriptions." It does not mention alternatives or when not to use it, so it falls just 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists the specific checks it performs, which gives insight into its scope (e.g., it checks for certain performance anti-patterns). However, it does not explicitly state that this is a read-only static analysis, whether it modifies files, or any limitations (e.g., it only catches these patterns, not all performance issues). This ambiguity leaves some risk of the agent misjudging side effects.

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

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

The description is front-loaded with the core purpose ('check for runtime cost that shows up as dropped frames') and then lists specific checks in a comma-separated enumeration. This is efficient and well-structured. It is slightly long due to the detailed list, but each item is distinct and adds value, so it earns its length.

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

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

The tool has an output schema (though not shown in detail), so the description correctly omits return-value specifics. It covers the purpose, the specific checks, and the appropriate usage context. A minor gap is the absence of a note that this is a static analysis tool that does not build or modify the project, but this is a relatively small omission given the clear scope.

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

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

The single parameter 'path' is fully described in the schema with 'Absolute path to the Swift project root (the folder containing Package.swift or the .xcodeproj).' Schema description coverage is 100%, so the schema already provides complete parameter semantics. The description adds no additional parameter-level information, which is acceptable per the baseline of 3 for 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?

The description states a specific verb ('check for runtime cost') and a clear resource ('SwiftUI and Swift performance'). It enumerates concrete anti-patterns (DateFormatter in body, non-lazy stacks, etc.), which makes its scope precise. This clearly distinguishes it from sibling review tools like review_swift_architecture or review_swift_concurrency, which target different concerns.

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

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

The description explicitly provides usage triggers: 'Use when scrolling stutters, launch is slow, or before shipping a list-heavy screen.' This gives clear context for when to invoke the tool. It doesn't explicitly name alternatives or state when not to use it, but the triggers are specific enough to guide an agent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly lists the security checks the tool performs, which makes its behavior transparent—an agent knows exactly what to expect the tool to scan for. It does not mention side effects or performance, but for a static analysis/review tool, this level of detail is more than adequate. The description adds significant value beyond the schema.

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

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

The description is long but each clause is information-dense and serves a purpose: it lists specific security checks that distinguish the tool and guide the agent. It starts with the primary action and then enumerates the checks. While it could be tightened, the structure is logical and each item adds value, especially for an agent deciding whether to invoke it. It's more than minimal but not bloated.

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

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

The description covers the tool's purpose, usage context, and a comprehensive checklist of what it detects. Since an output schema exists (indicated in context), the description does not need to describe return values. The tool is a security review for Swift projects, and the description covers the main use cases and expectations. Nothing critical is missing for a correct invocation—only the exact output format 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?

The input schema already fully describes the single parameter 'path' with a clear definition ('Absolute path to the Swift project root...'). Schema description coverage is 100%, so the baseline is 3. The description does not add extra semantics about the parameter itself; it focuses on the tool's functionality. Hence, it neither improves nor degrades the parameter clarity—it stays at baseline.

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 opens with a clear verb+resource ('Check a Swift project for security defects') and then enumerates a specific checklist of defect types (hardcoded keys, ATS disabled, etc.). This precisely distinguishes it from sibling review tools like review_swift_concurrency or review_swift_architecture, which focus on other concerns. An agent can immediately infer what this tool does and what it does not.

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

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

The description explicitly states usage contexts: 'Use before shipping, during a security review, or when handling credentials.' This gives clear when-to-use guidance. However, it does not explicitly mention when NOT to use it or alternative tools, so it misses the full 'when-not/alternatives' criteria for a 5. Still, the context is strong and 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?

With no annotations, the description carries the behavioral disclosure burden, and it does that well by listing exactly what it detects, including the no-tests edge case and the compile-issue detail about `await` in XCTAssert autoclosure. It does not explicitly state whether it modifies anything or whether it is purely read-only, but 'Check' and 'reports' strongly imply a non-mutating analysis 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?

The description is long, but every clause names a distinct, valuable defect category or usage condition. It front-loads the core purpose and then elaborates with specifics that help an agent decide and invoke correctly. There is no filler or repetition.

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

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

For a static review tool with one fully described parameter, the description is complete: it states the object of analysis, the defect categories checked, the scenario in which to use it, and the edge case of missing tests. Since an output schema exists, the absence of return-format details 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 100%, so the input schema already fully documents the `path` parameter. The description adds useful context that `path` should be the Swift project root, but the parameter-level meaning is already clear from the schema; the description does not need to do heavy lifting here.

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 ('Check') and a specific resource ('a Swift test suite'), then enumerates concrete defect categories, making it unmistakable what the tool does. It clearly positions itself as a review/analysis tool rather than a test runner like run_tests, and the specific defect list distinguishes it from sibling review tools.

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

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

The description explicitly says when to use it: 'Use when tests are flaky, before trusting a green suite, or when adding coverage.' These are actionable triggering conditions. It also implicitly sets it apart from run_tests and other review_swift_* tools by focusing on test-suite reliability rather than execution or general architecture.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the operation as checking/analyzing code and lists exactly what categories of defects it looks for, strongly implying a non-mutating review. It could be more explicit about read-only behavior and traversal scope, but it is still substantive and transparent.

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

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

The description is a single dense sentence with a clear lead clause and a compact list of specific defect categories, followed by a short, useful usage sentence. Every item earns its place and there is no filler or repetition.

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

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

For a one-parameter review tool with an output schema present, the description covers the target domain and the full set of checks without needing to explain return values. It does not explicitly discuss project-wide traversal or compare itself to sibling review tools, but the scope and usage are sufficiently clear for correct invocation.

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 only one parameter, path, and the schema describes it fully as the absolute path to the Swift project root. The description adds no additional parameter semantics, but 100% schema description coverage means the schema already carries that burden, 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?

Uses the explicit verb 'Check' with the resource 'SwiftUI code for view and state defects' and then enumerates concrete defect categories such as Dynamic Type issues, AnyView, deprecated .cornerRadius, and try!. This makes the tool's purpose unmistakable and differentiates it clearly from sibling review tools focused on concurrency, architecture, or memory.

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 ends with 'Use when reviewing or building SwiftUI screens', giving a clear context for when the tool applies. It does not explicitly name alternatives or state exclusions, but the SwiftUI-specific defect list makes the boundary versus sibling review tools reasonably obvious.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the core behavior (runs xcodebuild test), the target resource, and the destination requirement. However, it does not disclose potential side effects (e.g., build artifacts, derived data writes), runtime expectations, or what success/failure looks like, leaving gaps for an agent.

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

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

The description is three concise sentences, front-loaded with the action and purpose, and every sentence adds a distinct piece of information (action, usage context, precondition). There is no redundancy or fluff.

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

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

The tool has six parameters, no output schema, and no annotations, yet the description only covers the high-level purpose and the destination requirement. It does not explain how to choose between project and workspace, what scheme is needed, or what side effects/outputs the agent should expect. For a complex build/test tool this is incomplete.

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 0%, so the description must compensate for documenting all six parameters. It only mentions project/workspace and the destination requirement, leaving scheme (a required parameter), configuration, and derivedDataPath unexplained. This is insufficient for an agent to construct a correct call without external knowledge.

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

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

The description clearly states the action ('Run xcodebuild test') and the resource ('a project or workspace'), and adds a timing context ('before visual review') that distinguishes it from sibling review tools. It does not explicitly name an alternative sibling, so it falls short of full differentiation.

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 a clear context for when to use the tool ('verify runtime/test behavior before visual review') and states a key precondition ('Requires an explicit destination'). It does not mention exclusions or point to alternatives like build_project for compilation-only tasks, so it lacks explicit when-not 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention prerequisites (e.g., simulator must be booted), whether the operation is read-only, or what happens if the simulator is not available. The includeImage parameter is not explained, and no side effects or failure modes are described. This is a significant gap for a tool with zero annotation coverage.

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

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

The description is extremely concise: two sentences with no filler. The main action is front-loaded, followed by the usage purpose. Every word earns its place, and it is well-structured for quick scanning by an agent.

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

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

For a simple tool with three parameters and no output schema, the description leaves important gaps: it does not explain the includeImage parameter, does not state prerequisites like a booted simulator, and does not indicate whether the command can fail or what the response looks like. The description provides only the core action and a use case, which is insufficient for an agent to invoke it correctly without additional assumptions.

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

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

The description does not add any meaning about the parameters beyond the schema. The schema already describes udid and outputPath, but includeImage has no description in the schema. With 67% schema coverage (moderate), the description should compensate by explaining the undocumented parameter, but it does not. It only mentions 'PNG path' which echoes outputPath without adding value.

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

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

The description clearly states the action (capture a simulator screenshot), the output format (PNG path), and the underlying command (xcrun simctl io screenshot). It also gives the intended purpose (evidence for visual review and before/after comparison), which makes it unambiguous and distinct from other simulator tools like preview or show.

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

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

The description provides a clear usage context: 'Use as evidence for visual review and before/after comparison.' This tells when it is appropriate, but it does not explicitly mention when not to use it or contrast it with alternatives like simulator_preview_start. No exclusions are stated, so it earns a 4 rather than 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 establish read-only, idempotent, non-destructive behavior, so the description's main contribution is the closed-world scope ('bundled 405-entry source snapshot'), consistent with openWorldHint=false. It does not disclose query matching semantics, ordering, or result shape, but for a read-only search tool with these annotations this is an adequate baseline. No contradiction 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?

A single front-loaded sentence that packs the verb, resource, scope, and corpus size with no filler. Every phrase 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 low-complexity search tool, annotations cover safety and idempotence, the schema fully constrains the two parameters, and the description defines the scope precisely. The only notable omission is the return-entry shape, but since no output schema exists, the agent can reasonably infer a list of matching technologies.

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 0%, but the description partially compensates by defining the searchable corpus and item types, clarifying what 'query' will be matched against. 'limit' is fully constrained by the schema and needs little extra explanation. It does not explain fuzzy/prefix matching or how limit affects results, so it stays at a 3.

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

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

The description states a specific action ('Find') over a well-defined resource ('Apple frameworks, tools, services and legacy technologies') and adds a precise scope ('bundled 405-entry source snapshot'). It is clear but does not explicitly contrast with sibling tools such as get_apple_technology or search_local_references, so it earns a 4 rather than a 5.

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

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

The description implies the tool is for querying the bundled Apple technology snapshot, which is enough to signal its general niche. It does not state when to prefer this over search_local_references or get_apple_technology, nor does it give exclusions. This is implied usage rather than explicit 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 and idempotentHint=true, so the safety profile is known. The description adds meaningful behavior beyond that: 'Returns compact file matches without loading bodies' and 'Source files and guide code blocks have different verification status,' which help set expectations for the response and result interpretation.

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 deliver the core purpose, return style, and an important result nuance without repetition or filler. The most important information is front-loaded in the first sentence.

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 3-parameter search tool with safety annotations, the description covers the main action and return behavior, but the 'different verification status' comment is vague and there is no mention of result structure or limit behavior. An agent can invoke it, but may be uncertain about interpreting results.

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

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

With schema description coverage at 0%, the description must compensate for the undocumented parameters. It hints at the source/guide distinction through 'Swift source' and 'guide code blocks' but does not explain the 'kind' enum, 'limit', or 'query' semantics. The agent is left without concrete guidance on parameter values beyond the raw schema types.

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 opens with a specific verb and resource: 'Search complete repository guides, Swift source, templates and assets offline.' This clearly conveys the tool's scope and differentiates it from online searches by noting it operates offline. However, it does not explicitly name or contrast any sibling tool, so it stops short of full differentiation.

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 guidance is given about when to choose this tool over alternatives such as search_apple_technologies, read_local_reference, or get_reference_outline. The description implies a local search use case but never states exclusions or conditions, leaving the agent to infer selection criteria.

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

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

No annotations are provided, so the description carries the full burden. It mentions the underlying command (xcrun simctl boot), implying it launches a system process, and clarifies that it does not erase or reset content. However, it does not mention potential side effects like boot time or whether it waits for boot completion, which could be relevant for an agent.

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

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

Three sentences with no fluff. The key action is front-loaded, and the usage guidance and exclusions are direct. 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?

Given the simple tool (1 parameter, no output schema), the description covers purpose, usage, and a key exclusion. It could mention that booting may be asynchronous or require waiting, but for the tool's simplicity, this is nearly 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?

The schema already describes the udid parameter with a helpful hint (use simulator_list first). Schema coverage is 100%, so the description doesn't need to add more. It adds no further semantics beyond the schema, so a 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 ('boot') and resource ('simulator by UDID'), with the exact command (xcrun simctl boot) and a clear scope: it does not erase or reset content. This clearly distinguishes it from sibling tools like simulator_shutdown and simulator_show.

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 states when to use this tool: before install_app, launch_app, screenshot, or open_deep_link, which are siblings. It also clarifies what it does not do (erase/reset), preventing misuse. This is excellent 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?

No annotations are provided, so the description carries the full burden. It explicitly states it reports information and does not modify Xcode, which is a clear behavioral constraint. However, it doesn't disclose error scenarios or return format, but for a simple reporting tool this is sufficient.

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

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

Two sentences with zero filler. The primary purpose is front-loaded, followed by a clear exclusion. Every word 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 zero-parameter, no-output-schema reporting tool, the description fully covers what is reported and what is not done. Nothing essential is missing for an agent 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters; it correctly focuses on behavior.

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

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

The description states a specific verb ('Report') and resource (Xcode, runtimes, device profiles), and even clarifies what it does not do ('Does not download or update Xcode'). This clearly distinguishes it from action-oriented siblings like simulator_boot or install_app.

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 to use it (when you need environment info) but does not explicitly mention alternatives or conditions to avoid it. The 'Does not download or update Xcode' hints at non-usage but doesn't name specific sibling tools.

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

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

With no annotations, the description carries the behavioral burden. It conveys a read-only enumeration action ('List') and implies UDIDs are available in the result, but it does not state the return format, whether unavailable devices are included, or explicitly confirm it has no side effects. The core behavior is clear but minimally elaborated.

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 with no filler. The first states the action and mechanism; the second states when to call it. 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 zero-parameter read-only list tool with no output schema, the description is largely complete: it provides the action, mechanism, and timing relative to action-oriented siblings. A minor gap is the lack of an explicit note about the exact output shape, but the UDID usage hint partially covers that.

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

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

The tool has zero parameters, so no parameter documentation is needed and the baseline is 4. The description adds no parameter details, but none are required for correct invocation.

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

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

The description states a specific verb ('List') and resource ('available Simulator devices') and adds the implementation mechanism 'xcrun simctl'. The second sentence distinguishes it from booting, installing, launching, and screenshot tools by positioning it as the prerequisite lookup when the UDID is unknown.

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 explicitly says to use the tool 'before booting, installing, launching, or capturing screenshots when you do not know the simulator UDID', which is clear when-to-use context. It does not name alternative tools or explicitly state when not to use it, 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?

With no annotations provided, the description carries the full burden. It discloses that the viewer is token-protected, loopback-only, read-only, and not a public hosted simulator. It also notes that interaction must occur in the native Simulator. This is meaningful behavioral context beyond the schema, though it could mention what happens if the device is not booted or how the token is scoped.

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, each earning its place: what it starts, where to open the URL, and what the preview is not. The key constraint (token-protected loopback) is front-loaded, 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 single-parameter tool with no output schema, the description covers the essential behavior, usage context, and limitations. It could be more complete by stating what the returned URL looks like or what happens if the device isn't booted, but the description is sufficient for an agent to invoke it correctly in most cases.

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

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

Schema coverage is 100% and the only parameter (udid) is already described in the schema. The description adds the prerequisite that the device must be booted and references simulator_list for uncertainty, which is useful context beyond the schema. With full schema coverage, the baseline is 3, and the added booted-device context justifies a 4.

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

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

The description states a specific verb ('Start'), a specific resource ('token-protected loopback screenshot viewer'), and a target device ('booted device'). It also distinguishes itself from a public hosted simulator and from native interaction, making its purpose clear relative to siblings like simulator_show and screenshot.

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 says to open the returned URL in the client sidebar/browser and clarifies that interaction happens in the native Simulator, not the preview. It does not explicitly name alternative tools or when-not-to-use conditions, but the context is clear enough for an agent to know when this tool is appropriate.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently discloses two side effects: removing temporary screenshots and leaving the Simulator running. It does not mention whether the preview server itself remains alive or any cleanup of in-memory state, which would be useful, but the stated behavior is clear and honest.

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, information-dense sentence with no filler. The primary action, side effect, and exclusion ('leaves the Simulator running') are all packed in efficiently, and 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 one-parameter tool with a fully described schema and no output schema, the description covers the essential behavioral context: what is stopped, what is cleaned up, and what remains running. It is complete enough for an agent to invoke correctly, though it could mention whether the action is idempotent when no preview exists.

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

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

Schema coverage is 100% and the udid parameter is already described, including a pointer to simulator_list. The description adds no new parameter detail, which is acceptable at this coverage level. Baseline is 3, with a slight uplift because the single parameter is unambiguous and the schema's guidance is already actionable.

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 ('stop') and resource ('this server's preview for a device') and clearly distinguishes from sibling tools by mentioning what it does NOT do ('leaves the Simulator running'). It is immediately clear this is the inverse of simulator_preview_start, not simulator_shutdown or simulator_boot.

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 tells when to use this tool ('to stop this server's preview for a device') and the sibling context makes the alternative obvious. It does not explicitly state when NOT to use it or name alternatives like simulator_shutdown for stopping the entire simulator, so it falls just 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool boots a device and waits, which implies a mutating action and a possible delay. However, it does not explicitly state prerequisites (e.g., Xcode availability), failure modes, or whether the device must already be available. The behavior is partially transparent but lacks depth.

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

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

The description is a single concise sentence that front-loads the key action (boot and wait) and clearly states the outcome (open window for interaction). No wasted words; it is appropriately sized for the tool's simplicity.

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 tool with one parameter and no output schema, the description covers the essential behavior: booting, waiting, and opening the window. However, it lacks details like whether the tool is blocking, how long the wait might be, or error scenarios (e.g., if the UDID is invalid). Given the low complexity, this is adequate but not thorough.

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

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

Schema description coverage is 100% and the parameter udid is well documented ('Simulator UDID. Use simulator_list first when unsure.'). The description adds minimal extra meaning, only implying the device must be 'available'. This is sufficient but not additive beyond the schema.

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

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

The description clearly states the tool's purpose: boot a device and open its native Simulator window for interaction. It uses specific verbs (boot, open) and identifies the resource (native Simulator window). However, it does not explicitly differentiate from the sibling tools simulator_boot and simulator_list, which might be confused with this 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?

The description does not provide explicit guidance on when to use this tool versus alternatives like simulator_boot or simulator_list. While the parameter schema hints 'Use simulator_list first when unsure', this is not in the tool description itself, and no exclusions or alternatives are mentioned.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully states that the operation 'does not erase content,' which prevents the agent from assuming destructive side effects. However, it does not mention behavior when the simulator is already shut down or what happens to running apps/state, leaving some behavioral gaps.

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, each earning its place: the action and method, the intended usage moment, and a key non-destructive clarification. The description is front-loaded and contains no filler or redundant restatement of the tool 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?

For a simple one-parameter lifecycle command with no output schema, the description is complete: it identifies the target, the command, the appropriate timing, and clarifies that content is preserved. There is no missing information an agent would need to invoke this tool correctly in the stated workflow.

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

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

Schema description coverage is 100%, and the schema already explains the udid parameter and advises using simulator_list first. The tool description adds only 'by UDID' and the post-validation timing, which slightly reinforces but does not meaningfully extend the parameter semantics. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Shut down a simulator by UDID using xcrun simctl shutdown.' It clearly differentiates this from sibling tools like simulator_boot and simulator_list by focusing on the cleanup/shutdown action. The added context 'Use after runtime validation to clean up a booted simulator' reinforces the purpose.

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 an explicit usage context: 'Use after runtime validation to clean up a booted simulator.' This tells an agent when the tool is appropriate. It does not explicitly name alternatives or exclusion cases, but the one-parameter design and clear shutdown purpose make the intended use 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?

The description discloses that the tool only affects running apps and explicitly says it does not uninstall or reset state, which is useful non-destructive context. However, with no annotations, it omits what happens if the app is not running, whether a booted simulator is required, or any error behavior, leaving the agent to guess.

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 front-loads the action and immediately clarifies what the tool does not do. There is no filler; every phrase contributes meaning, making it easy to scan and understand.

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 two-parameter mutation tool with no annotations and no output schema, the description covers the core action and the key non-effect. It lacks failure-mode details and prerequisites (e.g., simulator must be booted, app must be installed), but for such a simple tool these gaps are 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?

The schema covers 'udid' with a description, but 'bundleId' has none. The description's phrase 'by bundle identifier' merely echoes the parameter name and adds no format, examples, or validation. Since schema description coverage is only 50%, the description should compensate for the undocumented bundleId parameter, but it doesn't.

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

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

The description states a specific verb ('Terminate'), a specific resource ('running simulator app'), and the method ('by bundle identifier'). It explicitly differentiates itself by noting what it does NOT do ('without uninstalling it or resetting its state'), which helps distinguish from sibling actions like install_app or launch_app.

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 'without uninstalling it or resetting its state' gives a clear usage boundary: use this when you want to stop an app but preserve its data. It does not name alternative tools explicitly, but the context is strong enough that an agent can infer when to choose this over other simulator commands.

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