ShipSwift

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description's only added context is the deprecation/back-compat status, and it never confirms that behavior is identical to getSkill or that the alias will eventually be removed.

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 short sentence, front-loaded with the essential fact and free of filler. It is arguably over-compressed for a tool whose actual function is never named, but nothing is wasted.

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

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

For a simple one-param read tool with full annotation coverage and a well-documented schema, most of what an agent needs is elsewhere. The remaining gap is knowing whether this is fully equivalent to getSkill and whether it is safe to migrate away from it.

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

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

Schema description coverage is 100% and the single 'id' param is documented in-schema with concrete examples ('animation-shimmer', 'auth-cognito'). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description never states the verb or resource itself — it only says this is the 'old name of getSkill.' A reader must already know what getSkill does to know that this retrieves a skill/recipe by ID. It does, however, position the tool relative to sibling getSkill, which is more than a bare tautology.

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?

'Kept for existing setups' implicitly routes new callers to getSkill while sanctioning use here for legacy integrations, which is real steering toward the correct sibling. The steer is implied rather than an explicit 'use getSkill instead', and it says nothing about the listRecipes/searchRecipes family.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful return behavior beyond annotations: complete Swift source, architecture explanation, implementation steps, and optional backend code for module skills. It does not mention error or not-found behavior.

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

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

Two sentences, front-loaded with purpose and then return detail. Every sentence contributes useful information with no filler.

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

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

For a single-parameter read tool with full annotations and no output schema, the description covers purpose and return contents well. A minor gap is the absence of not-found or error behavior.

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

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

Schema description coverage is 100%, and the id parameter already documents format with examples. The description only repeats 'by ID' and adds no additional parameter semantics.

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

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

The description states a specific verb and resource: 'Get a skill by ID.' The return-content sentence reinforces that this retrieves a single skill, implicitly distinguishing it from listSkills/searchSkills, though no sibling is named.

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

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

There is no explicit when-to-use guidance or routing to alternatives. An agent can infer a known ID is required from 'by ID', but the description never says to use searchSkills/listSkills to find an ID or when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so safety needs no restating. The description's added value is the deprecation/alias fact, which is genuinely useful behavior context. It does not confirm that results are identical to listSkills or flag any deprecation warning, so the disclosure is partial.

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 short fragment with zero filler; the most decision-relevant fact (it is the old name of listSkills) is front-loaded. It reads as a note rather than a tool statement, but nothing is wasted.

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

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

For a one-optional-param read tool with full annotations and no output schema, the bar is low, and identifying it as a legacy alias covers the key decision. Still missing is whether the alias returns identical results to listSkills or carries any deprecation caveat, which matters when choosing between the two.

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%; the single 'category' parameter has an enum and its own description with default 'all'. The tool description adds nothing about the parameter, 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 defines the tool only indirectly, as 'the old name of listSkills'. It never states in its own terms that it lists recipes/skills or what a 'recipe' is, so an agent must open listSkills or infer the resource. The sibling reference does anchor the operation, which is enough for minimum viability but not a self-standing purpose statement.

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?

'Kept for existing setups' is a clear legacy/back-compat signal and it names the sibling that supersedes it (listSkills), which routes the agent effectively. It stops short of an explicit 'prefer listSkills for new work' instruction or any statement about when this alias will be removed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds useful content context ('not a tutorial', production-ready code) but nothing about result size, pagination, or ordering — modest value on top of the annotations.

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

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

Purpose leads the description, followed by the value proposition and then the category inventory. The framework enumeration (Swift Charts, SpriteKit, Vision, AVFoundation, StoreKit 2, NavigationStack, AWS CDK, Hono, Cognito, DynamoDB) is longer than needed for tool selection and could be trimmed.

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

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

For a read-only, zero-required-parameter listing tool with no output schema, the description is adequate about scope. It never indicates what identifying fields a returned skill carries (name/id) — information an agent needs to chain into getSkill — leaving a gap in the retrieval 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 coverage is 100% and the single parameter is a self-documenting enum with a default, so the baseline is 3. The description's category list ('animations, charts, UI components, full-stack modules') loosely enriches the enum values but does not map them explicitly or explain what 'module' contains beyond examples like auth, camera, subscriptions.

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

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

States a specific verb and resource: 'List production-ready SwiftUI skills', and adds that each item is a complete copy-paste-ready implementation. It does not, however, differentiate itself from the sibling searchSkills or explain the list-vs-search distinction.

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?

Browsing a catalog is implied by 'List' and the category filter, but there is no explicit guidance on when to use this versus searchSkills, or a note that getSkill is the follow-up for fetching a single item. Usage must be inferred from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-structured information: that this tool is a deprecated alias with an identical-purpose replacement, which affects whether an agent should call it at all. It omits whether behavior is byte-identical to searchSkills (same params, same results), which would be the final piece.

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

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

One sentence, zero padding, and the most decision-relevant fact (it is the old name of another tool) is front-loaded. Slightly under-specified rather than verbose.

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 read-only search alias this is close to enough, but it leaves open whether the alias behaves identically to searchSkills and whether its query syntax matches. With annotations and a complete schema the gap is modest, so a 3 rather than lower.

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

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

Schema description coverage is 100% and the single query parameter is documented with examples, so the schema carries the load. The description adds nothing about parameter semantics, which is the baseline expectation for a fully documented single-param tool.

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 never states the verb+resource directly; it only says this is the 'old name of searchSkills', so the agent must infer that it searches skills by analogy with the sibling. That inference is easy given the name and sibling list, but it is still inference rather than an explicit statement of what the tool does.

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?

'Kept for existing setups' implies this is a legacy alias and hints that new callers should use searchSkills, but it never explicitly says 'prefer searchSkills' or states when this alias is still the right choice. The routing signal is present but implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without the description. The description adds one useful behavioral fact — that search reaches into full source code, implying broad match scope — but says nothing about result ordering, result caps, or pagination for what could be a large result set.

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

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

Two sentences, both front-loaded: the mechanism first, then the applicability. The example list is compact and functional rather than filler.

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

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

With one fully documented parameter, rich annotations, and no output schema, the description covers nearly everything an agent needs to invoke it correctly. The only real gap is what a search returns in shape and volume, which matters because matching against full source code could produce large 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by specifying which fields the query string is matched against (titles, descriptions, tags, full source code) — that is real semantics about how the input is interpreted. It stops short of describing matching rules (substring vs fuzzy, case sensitivity, multi-word 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?

States a specific verb and resource ('Search skills') plus the exact fields matched (titles, descriptions, tags, full source code), which tells an agent this is a keyword search rather than a lookup. It does not explicitly contrast itself with the sibling listSkills or getSkill, so the boundary must be inferred.

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

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

'Use for any iOS, SwiftUI, or backend topic' gives clear positive usage context, reinforced by a concrete keyword list (subscription, authentication, camera, paywall, infrastructure) that doubles as example use cases. There is no when-not guidance and no pointer to listSkills or getSkill as alternatives.

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