MagicScreenshots

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely valuable behavioral detail beyond the annotations: approving triggers 'final screenshot extraction,' revealing a downstream side effect. It still omits reversibility, whether re-approval is meaningful (non-idempotent), and permission requirements.

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

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

A single, front-loaded sentence with no filler; the action and its consequence are stated immediately. It is efficient, though its brevity borders on under-specification for a tool with meaningful side effects.

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 non-readOnly, open-world tool with zero parameter documentation and no output schema, the description omits prerequisites (a generated restyle must exist) and the meaning of both parameters. The agent knows what happens but not what to pass or when the call is valid.

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% for two parameters (group_id required, overview_url optional), so the description must carry the burden of explaining them. It mentions neither, leaving the meaning and expected format of group_id and overview_url entirely undocumented.

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 ('Approve'), a specific resource ('a generated restyle overview'), and the resulting action ('start final screenshot extraction'). It is clear and concrete, but it does not differentiate itself from the sibling create_restyle or otherwise orient the agent among related 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?

Usage is implied by 'a generated restyle overview' being the precondition, so an agent can infer this must follow a restyle generation step. However, there is no explicit when-to-use vs. when-not, no mention of prerequisites, and no routing to alternatives like create_restyle.

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

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

Annotations already declare the non-read-only, non-destructive, open-world profile. The description goes beyond that by disclosing the keyless-vs-keyed access model and the human claim/payment gate for restyle and localize, plus surfacing the claim_url handoff. It stops short of rate limits or return shape, but adds meaningful context.

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

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

Four tight sentences with the core action front-loaded. Each sentence carries workflow information rather than filler, though the access-tier breakdown is slightly list-like.

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

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

With no output schema, the description helpfully implies the claim_url handoff and explains the operational tiering an agent must understand before calling. For a one-optional-param create tool with annotations present, this is close to 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 100%, so the single optional 'name' parameter is fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Create an agent API key') and immediately clarifies the unusual 'without an account' condition. It does not explicitly contrast with sibling tools, but the operation is 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?

Gives clear conditional guidance on when the key matters versus not: directory browse needs no key, screenshot lookup works immediately, while restyle and localize require a human to claim and pay. This routes the agent on whether it even needs this tool, though it doesn't compare to named 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 this is a non-read-only, non-idempotent, open-world, non-destructive operation, so the mutation profile is covered. The description adds no behavioral detail beyond that fact – nothing about job queuing, latency, cost, or how to follow up on the created job.

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 names the action, resource, and scope with no wasted words. It is appropriately sized, though it errs toward under-specification rather than verbosity.

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 mutation tool with nested object parameters, two required fields, no output schema, and 25% schema coverage, the description should explain at least minimal input expectations and the async nature of job creation. As written it leaves the agent to guess how to supply source_app and screenshots.

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% and the description explains none of the four parameters. It never mentions limit (capped at 10), the source_app object's name/query/app_id/app_url/country fields, or source_screenshot_urls, leaving most inputs documented only by bare property names.

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 (Create) and resource (MagicScreenshots localization jobs) along with the input (source App Store screenshots) and target (one or more locales). It is clear what the tool produces, but it never distinguishes itself from sibling creation tools such as create_restyle.

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

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

There is no when-to-use guidance, no prerequisites (e.g. which source_app forms are accepted, whether a screenshot URL is required), and no reference to the sibling create_restyle or approval flow. The agent must infer its place in the workflow.

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 write/open-world/non-idempotent/non-destructive, so the bar is lower, but the description adds real value the annotations don't: an API-key auth gate and a human claim-and-pay step before the job executes. That cost/authorization constraint is exactly the kind of behavioral context the agent needs. It doesn't describe output or the subsequent approval step.

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

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

Three tight sentences with the core purpose front-loaded, followed by the preferred parameter and the hard prerequisite. The illustrative slug examples (duolingo, monzo, doordash) are compact and useful rather than padding. No wasted prose.

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 6-parameter write tool with nested objects and no output schema, the description covers purpose, routing, and the auth/payment gate. It omits the surrounding workflow – notably that a sibling approve_restyle exists, implying a review step – and gives no sense of what the call returns or how jobs are tracked. Adequate but with clear gaps.

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

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

Schema description coverage is only 33%, so the description is expected to compensate. It usefully disambiguates inspiration_slug (preferred over a free-text inspiration query) with concrete examples, but says nothing about source_app, inspiration_app, the screenshot URL arrays, or limit. Partial compensation for a low-coverage schema lands at 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?

States a specific verb and resource: restyling the user's App Store screenshots against a directory inspiration set. The agent can distinguish it from create_localize and get_screenshots by the 'restyle to match inspiration' framing. It stops short of explicitly naming sibling alternatives, keeping it at 4 rather than 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?

Gives a clear routing rule ('Prefer inspiration_slug from list_directory_apps') and a hard prerequisite (API key must be claimed and paid before generation runs). That tells the agent when the tool is usable and which parameter path to prefer. No explicit when-not or exclusion guidance is given.

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

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

Annotations already declare read-only/idempotent, so the description wisely adds non-annotation context: the Pro key requirement, the fallback response (a count of versions) without a key, and the newest-first ordering. Missing details on rate limits or result shape beyond the top-level fields.

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 dense and front-loaded: the return payload and ordering come first, then the use case and key prerequisite. No filler.

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

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

With no output schema, the description must carry the return contract; it does cover payload contents and ordering but omits how many results come back, what limit does, or how the fallback count is structured. Adequate but with clear gaps for a 2-param tool.

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

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

Schema coverage is only 50% – slug is documented but limit (default 10, max 50) has no description in either place. The description never mentions result count, limiting, or pagination, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource: returns every captured version of an app's App Store listing, with contents (screenshots and preview videos per date) and ordering (newest first). It doesn't explicitly distinguish itself from siblings like get_screenshots or get_app_videos, so it falls short of a 5.

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

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

Gives a concrete use case ("Shows how top apps change their creative over time") and a prerequisite (needs a Pro API key), plus the degraded behavior without one. It does not name alternative tools for related queries, so no 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?

Annotations already cover the read-only/idempotent safety profile, and the description adds genuinely new behavior: the access tier split (poster frames for anyone vs. Pro API key for mp4s), the link lifetime (1-hour download links), and the media characteristics (~30 s clips). Auth tier and expiry are exactly the kind of context annotations cannot express.

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 dense sentences, front-loaded with what is returned and the access-tier distinction before the usage note and the slug sourcing. No filler or restatement of the name/title.

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

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

With no output schema, the description carries the return-value burden and does so: poster frames and expiring mp4 links are explicitly named. Combined with the single fully documented parameter and supporting annotations, an agent has everything needed to 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?

Schema coverage is 100% and the single parameter is described there ('Library slug such as instagram'), so the baseline is 3. The description goes one better by stating the provenance of slug (list_directory_apps) and the has_video filter that finds apps with videos, adding selection guidance the schema lacks.

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

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

Names a specific verb+resource ('App Store preview videos for a library app') and immediately states what comes back: poster frames universally and mp4 download links under a Pro key. This clearly separates it from siblings like get_directory_screens and list_directory_apps, which list rather than return video assets.

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

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

Gives a concrete purpose ('use as reference when making your own app preview video') and routes the agent to the sibling that supplies the required input, naming both the tool (list_directory_apps) and the filter (has_video=true). No inference needed to know how to obtain a valid slug.

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 readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely useful context ('No API key required') and describes return contents, but omits return format details and pagination/limits – a modest add over 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 leads with the action and then enumerates the payload. Nothing is wasted, though the enumerations could be tightened slightly.

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

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

No output schema exists, so the description takes on the burden of listing return values, and it does so reasonably well. Annotations cover the behavioral profile, and parameters are fully covered by the schema; the definition is complete enough 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?

Schema description coverage is 100%, so all three parameters (slug, query, app_id) are already documented in the schema. The description adds no parameter-level detail beyond what the schema 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?

States a specific verb and resource ('Get one directory app') and enumerates the exact contents returned (metadata, screenshot URLs, related apps, create_restyle args). The singular 'one' implicitly contrasts with list_directory_apps, but the description never names that sibling to make the distinction explicit.

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

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

Usage is only implied by the singular 'one' versus the sibling list_directory_apps. There is no explicit statement of when to use this versus get_directory_screens or the list tool, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds non-obvious behavior: no API key is required, results are ordered, and the returned markdown images are intended for vision-model inspection — genuinely useful context beyond 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?

Four short sentences, front-loaded with what the tool returns, then localization, then index semantics, then the auth fact. Each sentence carries distinct information with no filler or repetition.

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

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

With no output schema, the description does the work of explaining the return content (ordered screenshots plus markdown images). It covers the three parameters and the no-auth fact. Minor gaps remain around out-of-range index behavior or empty-listing behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description adds meaning the schema does not: index is 1-based and matches the /apps/:slug/screens/:index route. It restates the country examples already in the schema, which is redundant but harmless.

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 ('Get the ordered App Store listing screenshots for a library app') and describes the payload shape (markdown images a vision model can inspect). It does not explicitly distinguish itself from the sibling get_screenshots or get_directory_app, so sibling differentiation is only implied by the 'directory' framing.

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

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

Gives clear context for the country parameter ('Pass country ... for the localized listing in that storefront') and cross-references get_directory_app for storefront discovery. There is no explicit statement of when NOT to use this tool versus get_screenshots, but the usage 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description contributes the useful detail that the read surfaces errors and final output URLs, but says nothing about polling cadence, terminal states, or how long results persist.

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, front-loaded sentence with no filler. It is terse to the point of being telegraphic, but nothing in it is wasted.

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

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

With no output schema, the description does well to preview the return fields (status, overview URL, errors, output URLs). However, for a status-polling tool the omission of lifecycle semantics and the entirely undocumented group_id leave the definition only minimally complete.

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

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

Schema coverage is 0% and the single required parameter group_id is neither typed with meaning nor described anywhere. The description does not explain what a group_id is, where it comes from (presumably create_restyle), or its format, so it fails to compensate for the coverage gap.

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

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

The description uses a specific verb ('Check') and names a concrete resource (restyle job group), then lists the fields of interest (status, overview URL, errors, final output URLs). That is enough to separate it from create_restyle and approve_restyle, though it never names a sibling explicitly.

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

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

There is no statement of when to call this, when not to, or which alternative to prefer. The polling-after-create workflow is only inferable from the phrase 'restyle job group' and the presence of create_restyle/approve_restyle siblings, not 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, openWorld, so the safety profile is covered. The description adds that these are 'known' hosted discovery files, implying well-known-path fetching, but says nothing about failure modes (unknown endpoint, 404) or response format. Adds only modest context beyond 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?

A single front-loaded sentence with the verb and resource first, then the enumerations. No filler, nothing redundant.

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 required enumerated parameter, no output schema, and full annotation coverage, the description supplies enough to select the right endpoint and understand what kind of document comes back. It stops short of describing return format or error behavior, but nothing critical to invocation is missing.

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

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

Schema description coverage is 0%, so the description must carry the load for the single endpoint parameter. It does meaningful work by grouping the raw enum strings into recognizable document categories (API catalog, Agent Skills, MCP, OAuth metadata, OpenAPI, llms.txt), making the enum values interpretable rather than opaque paths.

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

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

States a specific verb (Fetch) and a specific resource (agent discovery document), then enumerates the concrete document kinds the endpoints map to. An agent can distinguish this from siblings like get_magicscreenshots_markdown or get_magicscreenshots_site_summary, though it never names them explicitly.

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

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

There is no guidance on when to call this versus the sibling document tools (markdown, site summary), nor any note that the endpoint must be one of the well-known paths. Usage is only implied by the examples given.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds that the output is markdown and that only public pages are reachable, which is modest extra context but says nothing about pagination, caching, or error behavior for unknown routes.

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

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

A single front-loaded sentence with no wasted words. It is tight, though arguably underwritten for the number of sibling tools it must be distinguished from.

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 fetch with rich annotations and a self-documenting enum, most of what an agent needs is present, and no output schema means return details are not strictly required. However, it omits any hint of how it relates to the discovery document and site summary tools, which matters given the crowded sibling set.

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, and it only offers 'known ... page' for the single 'route' parameter. The enum values are largely self-documenting as URL paths, which limits the damage, but the description does not explain that route must be one of those enumerated paths or what each represents.

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 verb 'Fetch' and resource 'markdown representation of a ... public page' are specific, and the word 'known' signals that the page must already be identified. It stops short of distinguishing itself from close siblings such as get_magicscreenshots_discovery_document or get_magicscreenshots_site_summary.

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

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

'Known ... page' faintly implies you must already have a route rather than discovering one, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings. An agent has to infer whether to call this versus the site summary or discovery document.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that the content spans auth requirements and MCP tools, but says nothing about caching, size, or that it is parameterless and thus safe as a first call.

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

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

A single front-loaded sentence with no filler; every listed item (directory, routes, tools, auth) earns its place.

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

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

With no output schema, the description compensates by enumerating the summary's contents, which is effectively a return-value sketch. It is close to complete for a trivial parameterless overview tool, only lacking sibling 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Schema coverage is also 100%.

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 clear verb (Return) and resource (a concise summary of MagicScreenshots) and enumerates the covered topics: the screenshot directory, public routes, MCP tools, and auth requirements. It does not, however, differentiate itself from the very similar sibling tools get_magicscreenshots_discovery_document and get_magicscreenshots_markdown, which an agent would need help distinguishing.

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 an orientation/overview use case but never states when to call this versus the discovery document or markdown siblings. No exclusions or prerequisites are given, so the agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the directory path requires no API key, the live lookup requires one, and directory results include markdown images. It does not discuss pagination or rate limits, keeping it short of a 5.

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

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

Four tight sentences, front-loaded with purpose, followed by behavior and routing. Every sentence earns its place with no filler, though the routing sentence could be marginally tighter.

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 6-parameter, 0-required, read-only lookup with no output schema, the description covers the source-selection logic, the API key requirement, and the return format (curated listing shots with markdown images). It is nearly complete; only edge cases like missing-directory handling are unstated.

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

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

Schema description coverage is 83%, so the schema already documents most parameters, and the description largely restates the live/slug behavior rather than adding syntax or format details. Baseline 3 is appropriate given 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 opens with a specific verb+resource ("Fetch high-resolution App Store screenshots") and clearly distinguishes itself from siblings by naming get_directory_app as the alternative when a catalog slug is already available. An agent can tell what this does 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?

It explicitly states when to use this tool ("for the user's own app") versus the sibling ("use get_directory_app when you already have a catalog slug"), and documents the branching behavior (directory-first, live fallback, live=true to skip). Routing conditions are fully specified.

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 this as a safe, idempotent, non-destructive read, so the bar is lower; the description adds real value beyond that with corpus freshness ('refreshed daily'), coverage breadth ('thousands'), and 'No API key required'. It does not discuss rate limits or result caps, which the limit/offset params imply but the prose leaves silent.

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

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

Three tight sentences: scope first, filter axes second, returns/requirements last. Every clause carries information and there is no filler or restatement of the title.

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

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

For an 8-parameter search tool with no output schema, the description covers the corpus definition, filter dimensions, the shape of the return value ('slugs'), and the follow-up tools that consume it. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 88%, so the schema already documents nearly every parameter, including enum meanings for chart and platform. The description restates the same filter categories (text, tag, genre slug, chart rank, has_video) without adding syntax, defaults, or interaction rules (e.g., chart requires category), so baseline 3 applies.

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

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

States a specific verb and resource ('Search ... App Store listings') plus the exact scope of the corpus (top 100 free and top-grossing per Apple category, refreshed daily). This clearly separates it from siblings like list_directory_categories, list_directory_tags and get_directory_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 enumerates the five filter axes (text, genre slug, tag, chart rank, preview video) and names the downstream tools whose slugs it returns (get_directory_app, get_app_videos, get_app_history, create_restyle), which tells an agent where this fits in a workflow. It does not state when to prefer a sibling list tool instead, so it stops short of full when/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?

Annotations already declare the safe read-only/idempotent profile, so the bar is lower. The description still adds real facts beyond them: that results include app counts, and that no API key is required, which affects how an agent can call it. It does not describe pagination or result size, so not a 5.

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

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

Three short sentences, each earning its place: what is returned, when to reach for it, and the auth requirement. The core content is front-loaded 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?

With no output schema, the description carries the return-value burden and does mention categories and app counts. For a zero-parameter list tool that is nearly sufficient, though the exact shape of the returned items is left implicit.

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

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

The tool takes zero parameters, so the schema offers nothing to interpret and the baseline of 4 applies. The description correctly implies a no-argument enumeration rather than suggesting any filtering input.

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

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

States a specific verb (List) and resource (App Store screenshot directory categories), and adds concrete examples plus the payload detail ('with app counts'). It does not explicitly differentiate itself from close siblings like list_directory_apps or list_directory_tags, but the resource noun is specific enough to disambiguate.

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

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

'Use this first when an agent wants inspiration by genre' gives a clear triggering condition and even a sequencing hint relative to downstream tools. It stops short of naming an alternative or stating when-not-to-use, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so safety is covered. The description adds two things annotations do not: that results include app counts, and that no API key is required — useful auth context for a caller deciding whether the call will succeed.

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

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

Three short sentences, front-loaded with the resource and its concrete example values, followed by the disambiguation and the auth note. Every sentence adds distinct 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 zero-argument list tool with no output schema, the description conveys what is returned (tags plus app counts) and the access requirement. It does not mention what identifier form the tags take, which matters if the agent must pass a tag into a downstream tool — a minor but real 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter-related information is missing.

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

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

States a specific verb (list) and resource (directory tags), then defines what those tags actually are — listing-screenshot treatments with example values and app counts — and contrasts them with in-app UI patterns. An agent can distinguish this from list_directory_apps and list_directory_categories without opening any schema.

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

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

The description clarifies what the tags are conceptually, implicitly indicating usage for browsing/selecting creative treatments, but never states when to call this versus list_directory_categories or list_directory_apps, nor what a caller would do with the result. Usage is implied rather than guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description only adds a small amount of behavioral context by noting the response includes 'public guide routes' alongside languages, but says nothing about pagination, ordering, or whether the result set is exhaustive.

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

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

One tight sentence with the resource front-loaded and no filler. It is efficient, though arguably too sparse to earn a top score given the tool has an undocumented parameter.

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

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

With no output schema, the description carries responsibility for explaining the return value; it names the two content categories but not their shape, and it leaves the 'limit' parameter's effect unexplained. Adequate minimum, but with clear gaps.

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

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

The single 'limit' parameter has 0% schema description coverage and is never mentioned in the description. With a maximum of 50 and a default, an agent cannot tell from the text whether the full language list is returned by default or whether it is paginated/truncated.

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

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

States a specific verb ('Return') and the exact resources: supported screenshot localization languages and public guide routes. This lets an agent distinguish it from the similar-looking sibling list_magicscreenshots_markets by resource, though the description never explicitly names that sibling.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of an alternative tool. An agent can infer this is a reference-lookup call from the name, but the description adds nothing about context or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered elsewhere. The description adds no behavioral context of its own — nothing about pagination, the default/max limit of 100, ordering, or what 'public market routes' means.

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

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

A single tight sentence with no filler and the resource front-loaded. It is efficient, though it is arguably too terse for the amount of undocumented surface area.

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

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

With no output schema and zero parameter documentation, the description should explain the return shape and how region/limit shape results. Neither is covered, leaving the two optional parameters and the output format unexplained.

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 carry parameter meaning, but it never mentions the 'region' enum values or the 'limit' cap. 'supported markets' loosely gestures at filtering but gives no syntax or allowed values.

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

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

States a specific verb ('Return') and resource ('supported App Store market guides and public market routes'), so an agent knows this is a read-only listing tool. It does not, however, distinguish itself from the parallel sibling list_magicscreenshots_languages, and 'market guides' vs 'markets' is slightly opaque.

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

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

There is no statement of when to call this tool, what question it answers, or how it relates to list_magicscreenshots_languages or the get_magicscreenshots_* siblings. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds account scoping and the word 'recent', but never defines the recency window, ordering, or whether results are paginated, so behavioral context remains thin.

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 efficient sentence with no filler, and the scope constraint (authenticated account) is present. It is appropriately sized, though it could front-load the enumeration/recency behavior more explicitly.

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 list tool with annotations and no output schema, this is minimally adequate. However, the agent still cannot tell how many results come back, whether the list is truncated or paginated, or what fields an output contains.

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 one parameter (limit) with 0% schema description coverage, and the description never mentions it, its bounds, or what happens if it is omitted. Only the vague word 'recent' hints at recency ordering, which does not compensate for the unexplained limit control.

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

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

States a specific verb ('List') and a specific resource ('MagicScreenshots restyle job groups and outputs'), scoped to the authenticated account. It is distinguishable from the singular get_job_group, though it does not explicitly name that sibling as the retrieval alternative.

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

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

The description gives no when-to-use/when-not guidance and never points to alternatives such as get_job_group for a single job. The agent is left to infer that this is the broad enumeration call.

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