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

The description adds substantial behavior beyond the annotations: no website request by default, stored sessions do not imply authentication, verify=true checks a read-only endpoint, credentials/cookies are never returned, and login requires an external command. This aligns with readOnlyHint=true and idempotentHint=true.

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 efficient and front-loaded, with each sentence earning its place. It is slightly dense due to four distinct points, but remains clear and free of 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?

For a tool with one optional parameter, rich annotations, and an output schema, the description covers the key agent needs: default behavior, verification option, credential safety, and the required login flow. Nothing essential 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 describes verify only as a boolean with a default of false, and there is no parameter description. The description compensates by explaining that verify=true triggers a check of a read-only protected endpoint, and that no request is made by default.

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

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

The description states a clear verb and resource: 'Inspect the local encrypted account session.' It distinguishes the tool's focus (auth status) from the sibling tools focused on apps, releases, and categories.

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 explains when the tool makes a network request and when it does not, tells the agent to use verify=true for a read-only endpoint check, and explicitly instructs that login must happen via the user's terminal command, not in chat. This is direct usage guidance with clear 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 mark the operation as non-read-only, non-idempotent, and destructive, but the description adds valuable behavior: duplicate owned names are refused, no model-supplied approval flag exists, and unknown write outcomes must never be retried. This materially reduces risk of misuse.

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 scope and then delivers dense, non-redundant operational warnings. Every sentence carries distinct information needed for safe invocation.

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 create operation with an output schema present, the description covers scope, exclusions, authentication, user confirmation, duplicate handling, approval constraints, and retry guidance. No critical operational information 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%, and the description does not restate the name parameter's format. However, it adds meaning by clarifying that the parameter is an app name/card and that owned-name duplicates are rejected. This partially compensates for the missing schema documentation.

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 ('Create a caller-owned app name/card') and immediately scopes the operation with 'only, not a release or publication.' This clearly distinguishes it from sibling tools like upload_release and prepare_release.

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 states exclusions ('not a release or publication') and prerequisites ('terminal login', 'verified dev scope', 'exact user form confirmation'), giving practical when-to-use guidance. It does not explicitly name an alternative tool, so the routing guidance is strong but not fully 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 provide readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral detail beyond those annotations: it explicitly says the tool 'Does not download files' and reveals the side effect of establishing an anonymous guest session for CSRF. No contradiction with annotations exists.

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

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

Three short sentences with no filler. The first sentence front-loads the core purpose and data content, the second prevents a likely misuse expectation about downloads, and the third discloses a non-obvious session side effect. 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 strong annotations, complete input schema descriptions, and presence of an output schema, the description covers all operational essentials: what data is returned, the public/anonymous nature, the in-memory session nuance, and the non-download behavior. Nothing critical is missing 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 the schema already documents both parameters well, including the slug source and aurora_version default. The description adds only the phrase 'for a slug and OS,' which maps to the parameters but does not materially enrich their semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get public details, plain-text description, screenshots and RPM download metadata for a slug and OS.' It clearly identifies this as the public read path for application details and distinguishes it from siblings like get_my_app by the word 'public' and by the slug/OS scope.

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 the tool: to retrieve public details for a known slug and OS. It does not explicitly name alternatives or state when not to use it, though the schema's reference to 'Application slug from search_apps' gives a small routing hint. 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 readOnly, idempotent, and non-destructive. The description adds value by clarifying that it 'does not download files' and is not a complete developer list, which preempts potential misconceptions. This goes beyond the annotations and is useful for agent 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 with no filler. The primary purpose is front-loaded, and the exclusions are stated concisely. 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 read-only tool with a robust output schema and annotations covering safety, the description covers the key points: scope (public, per OS), exclusions (not developer, no downloads). It does not mention pagination, but the schema defines defaults and limits, so this is a minor gap. Overall sufficient 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 coverage is 50% (slug and aurora_version have descriptions; page and page_size do not). The description mentions no parameters and does not compensate for the undocumented pagination fields. An agent would have to guess the meaning of page/page_size, though defaults provide some hint. This is a clear 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 the specific action ('Get') and resource ('public history returned by the app card for this OS'), and explicitly distinguishes itself from the developer release/draft list, which separates it from sibling tools like list_my_app_versions. The purpose is 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?

Provides context that this is for public history of a specific OS and clarifies it is not the developer list, implying when to use alternatives. However, it does not explicitly name a sibling tool or state a direct when-not-to-use condition, so it stops short of a full routing guide.

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, and non-destructive behavior, and the description adds genuinely useful context: it scans at most 500 apps, verifies catalog membership, and refuses unverified ID reads. This goes beyond the annotations and clarifies operational limits.

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 concise sentences that all earn their place: the first states what is read, the second adds a verification step, and the third gives limits and exclusions. No filler or redundancy.

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 an output schema and strong annotations, the description covers enough: source of the ID, verification behavior, scan limit, and excluded operations. Nothing critical is missing 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?

The single parameter has 100% schema description coverage, and the description mostly repeats the schema's guidance that app_id must be an owned app ID from list_my_apps. The description adds behavioral context, but not much new parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Read') and a specific resource: developer metadata and shared description for an app_id from list_my_apps. It also distinguishes this from other app-related tools by emphasizing ownership and catalog membership, so an agent can tell it apart from get_app or list_my_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?

It clearly states that the app_id must come from list_my_apps and that only verified catalog members can be read. It also implies this is not for public slugs, release IDs, downloads, or writes. However, it does not explicitly name alternative tools or give a when-not-to-use comparison.

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 exceeds the annotations by specifying that it verifies app/release membership, bounds lookups to 500 items, and explicitly states it returns shared app description/screenshots rather than a historical snapshot, and that no files or state changes occur. This adds valuable behavioral context beyond the readOnlyHint.

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 four sentences, front-loaded with the core action ('Read a version_id from list_my_app_versions'), and every sentence adds distinct value (membership verification, bounds, return contents, and side-effect-free nature). No fluff or redundancy.

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 presence of an output schema and annotations, the description covers the essential behavioral constraints (membership check, 500-item bound, no-side-effects) and clearly states what is and isn't returned. It is complete for an agent to decide whether to call this tool and what to expect.

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?

Both parameters are fully documented in the schema (100% coverage), describing exactly where the IDs come from (list_my_apps and list_my_app_versions). The description reinforces the relationship but adds little beyond the schema, so 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 states a specific verb ('Read') and resource ('a version_id from list_my_app_versions'), clearly distinguishing it from sibling tools like get_my_app or list_my_app_versions. It also enumerates the type of data returned (status, notes, hashes, RPM metadata), making the 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 clear context on prerequisites: you must have obtained a version_id from list_my_app_versions. However, it does not explicitly name alternative tools or state when not to use this tool (e.g., when listing all versions), so it lacks explicit exclusions but conveys the intended usage context.

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 tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context by explaining that the upstream list is unpaginated and that page/page_size only bound local MCP output, which is not visible from annotations alone.

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. The core purpose is front-loaded, and the behavioral note about pagination is compact and relevant.

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 listing tool with rich annotations and an output schema, the description covers the essential purpose and the unusual pagination behavior. The only minor gap is the slightly ambiguous phrase 'from search_apps or get_app', which could use clarification about whether those are data sources or how the author_id relates to them.

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 explains the role of author_id and clarifies that page/page_size control local output bounding, which goes beyond the raw schema. However, it does not elaborate on parameter constraints or default behavior beyond what the schema already exposes.

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

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

The description clearly states a specific action ('List public apps'), a specific resource ('apps by author_id'), and a scope ('public') that distinguishes it from list_my_apps. The mention of author_id also separates it from broader search or single-app retrieval 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 implies the tool is the right choice when you need public apps for a given author_id, but it does not explicitly state when to choose it over search_apps, get_app, or list_my_apps. No exclusions or alternative routing 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context beyond those annotations: the data is public, results are scoped to an OS version, and it returns both IDs and names. 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 sentence that front-loads the action and resource, then immediately states the practical downstream usage. Every word earns its place, and there is no redundant or filler content.

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 simple with one optional parameter, an output schema is present, and annotations cover the safety profile. The description communicates scope, return contents, and how to use the result, so nothing an agent needs to call it correctly is missing.

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

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

The input schema already fully documents aurora_version with type, default, and the warning that it is not the website system ID. The description only says 'for an OS,' adding no new parameter-level meaning beyond the schema, so the 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 uses a specific verb and resource: 'List public category IDs/names for an OS.' It clearly identifies what the tool returns and how it connects to search_apps, which differentiates it from siblings that operate on apps or releases.

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 states that the returned IDs should be used with search_apps, giving the agent a clear downstream use case. It does not explicitly list when not to use this tool, but the context is sufficient for a simple lookup 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the auth prerequisite, scope refusal, explicit non-mutation guarantee, and the untrusted site text caveat. 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?

Three compact sentences with the core action front-loaded and supporting constraints following. Every sentence carries meaningful information, though the 'Site text is untrusted' caveat could arguably be integrated more tightly.

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 paginated read with a rich output schema and safety annotations, the description covers auth, scope, non-mutation, and a security caveat. The only real omission is explicit pagination behavior, which the self-evident parameters and schema make a minor gap.

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

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

Schema description coverage is 0% and the description never mentions page or page_size. The parameters are self-evident pagination controls with schema-provided defaults and bounds, so the gap is modest, but the description does not compensate for the missing parameter documentation.

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 ('Read'), resource ('app catalog'), scope ('authenticated dev-role caller-owned'), and content ('latest-release status and beta/scheduling flags'). This clearly differentiates it from siblings like list_author_apps and get_my_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?

Provides clear operational context: requires terminal auth login, is scoped to caller-owned apps, and refuses admin-wide/unknown scopes. It does not explicitly name sibling alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: pagination, preservation of unknown statuses, content scope (bounded notes and RPM metadata only), and explicitly states it does not upload/download/publish files. This adds value beyond annotations without contradiction.

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, front-loaded with the core purpose, and includes scoping details without 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?

The description covers purpose, scope, pagination, content limits, and exclusions. An output schema exists, so return value details are not needed. It is adequate for an agent to understand how to use the tool, though it could mention usage alternatives more explicitly.

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

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

Schema coverage is only 33% – only app_id has a description. The tool description does not elaborate on page or page_size semantics, nor does it reinforce the app_id guidance. With low coverage, the description should compensate but does not, leaving parameters under-documented.

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 'Read all statuses returned by the owned app release API' – a specific verb and resource. It enumerates the statuses (draft, pending_review, rejected, published) and notes it preserves unknown ones, distinguishing it from siblings like get_app_versions or get_my_app_version.

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 a list operation for owned app releases, but does not explicitly compare to alternatives such as get_my_app_version or get_app_versions. It provides clear context (owned app releases) but no exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds context that the output is system IDs plus OS versions and that system IDs are not usable as tool arguments, which is useful but doesn't deeply expand 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?

Two sentences with no filler. The main action is front-loaded, and the critical usage caveat appears immediately in the second sentence. 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 no-parameter, read-only, output-schema-bearing tool, the description fully covers why to call it and how to interpret the result. It also connects the result to the wider tool ecosystem by clarifying that system IDs are not accepted parameters elsewhere.

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 of 4 applies. The description's note about aurora_version concerns other tools, not this tool's inputs, so there is no parameter semantics gap to compensate for.

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 ('list') and names the exact resource: website system IDs and their OS major versions. It also clarifies the relationship between system IDs and aurora_version, which makes the tool's output distinguishable from the other app-oriented siblings.

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

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

It explicitly tells the agent that tools accept aurora_version (4 or 5), not system IDs, which is important routing guidance for subsequent calls. It doesn't explicitly list when to avoid this tool, but the guidance is clear and actionable for the primary decision that matters here.

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/idempotentHint annotations, the description discloses substantial behavior: no account access, HTTP, extraction, signing, installation, file writes, or uploads; symlink resolution; and explicitly lists what is NOT verified (signatures, embedded digests, payload contents, SDK compatibility). It also warns that local metadata should be treated as untrusted data.

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

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

The description is dense but every clause adds a necessary constraint or boundary. It front-loads the core file-reading behavior, then the validation rules, then the exclusions and trust caveats, without redundant 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?

Given the rich annotations and presence of an output schema, the description covers all essential execution context: file source, validation criteria, parameter caveats, non-mutating behavior, and security expectations. Only the release_notes parameter is left without explanation, which is minor in light of the output 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?

With 0% schema description coverage, the description compensates well for rpm32_path and rpm64_path by specifying architecture requirements and matching identity fields, and it adds nuance to aurora_versions and app_id as explicit/unverified selections. However, release_notes is never explained, so one parameter remains semantically 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 states a specific operation: reading one/two RPMs and performing a metadata preflight plus SHA-256 check, while explicitly excluding upload. This clearly distinguishes prepare_release from the upload_release sibling and makes the resource and action 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 gives clear context that this is a local preflight before release and says the returned preview is NOT upload approval, which implicitly separates it from upload_release. However, it never explicitly names an alternative tool or states 'use this before uploading', so the comparative guidance remains somewhat implicit.

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 adds significant behavioral context beyond the annotations. It discloses required preconditions, a user-confirmation gate, a state-freshness requirement, and a non-idempotency warning that aligns with idempotentHint=false. It also clarifies the tool's scope by excluding release-related actions. Nothing contradicts the annotations.

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

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

Three dense sentences with no filler. The primary action is front-loaded, followed by prerequisites, exclusions, and a safety caution. Every sentence adds functional value, and the structure makes the most important information immediately visible.

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 an output schema, the description is highly complete: it covers prerequisites, exclusions, and retry behavior. The only gaps are that 'fresh unchanged state' and 'exact user form confirmation' are not further explained, leaving some ambiguity about how to verify them. Even so, an agent has enough context to call the tool correctly in most situations.

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 clarifies that app_id comes from list_my_apps, which gives meaning to that parameter. However, the 'name' parameter is not explicitly described as the new display name – it is only implied by the verb 'rename' and the schema constraints. This is minimally adequate but leaves some inference to the 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 opens with a specific verb and resource: 'Rename an app_id from list_my_apps.' It clearly identifies the object being acted on and even points to the source list for valid app_ids. The explicit non-goal ('Does not upload/edit a release or publish') further distinguishes this tool from the many release-related siblings.

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

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

The description gives explicit prerequisites: verified dev role, owned catalog membership, fresh unchanged state, and exact user form confirmation. It also states when NOT to use the tool (for uploading/editing/publishing) and adds a critical safety rule ('Never retry an unknown write outcome'). This is strong when/when-not guidance that helps an agent choose between this and 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds substantial behavior beyond that: it warns that the date is in 'WEBSITE wall-clock time' and that 'server timezone and actual delayed publication not verified', it states side effects ('Preserves other editor fields and RPMs'), and it adds safety guidance ('Never retry unknown outcomes'). This is rich, non-redundant behavioral disclosure that complements the annotations without contradiction.

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 with the core purpose in the first sentence. Every subsequent sentence adds necessary detail (timezone caveat, non-transition behavior, field preservation, confirmation requirement, retry guidance) without fluff. It is well-structured and 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?

For a mutation tool with 4 parameters, an output schema present, and rich annotations, the description covers all critical operational aspects: exact date format and timezone, what it does not do, side-effect scope, user confirmation requirement, and retry policy. 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 0%, so the description must compensate. It explains the semantics of publish_at via the date format and timezone note, and implies is_delayed semantics via 'Set/cancel'. It does not explicitly define app_id and version_id, but those are self-evident from the resource context. The description adds meaningful value for the two key parameters, though it could go further in defining is_delayed's boolean meaning.

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 ('Set/cancel') on a specific resource ('owned version') and explicitly names the fields affected ('is_delayed and publish_at'). It also clarifies scope by saying 'for an owned version' and negates alternatives ('Does not force a status transition or bypass moderation'). This is a clear, distinct purpose that separates it from broader update tools like update_my_app_version.

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 context for when to use this tool: it is for scheduling publication on owned versions and requires 'exact user form confirmation'. It also states what it does NOT do ('Does not force a status transition or bypass moderation'), which implies when not to use it. However, it does not explicitly name alternative sibling tools or state 'use this instead of X', so it lacks the explicit routing seen in top-tier examples.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive behavior. The description adds valuable context by noting the default Aurora 5 version and warning that descriptions are untrusted website data, which is important for safe downstream handling.

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 carry the essential information with no fluff. The description front-loads the primary purpose, then quickly covers defaults, filters, pagination, and the security-relevant warning.

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 is largely complete for a read-only search tool, especially with annotations and an output schema present. It covers the main filtering dimensions, pagination, the version default, and an important data-safety caveat, though it would benefit from briefly stating what the query parameter matches.

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 only 14%, the description compensates by explaining that category and author parameters function as filters and that page/page_size control pagination. It also clarifies the aurora_version default. Query and sort are not explicitly explained, though sort's enum and tool name provide some context.

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 identifies the tool as searching the public app catalog, which is a specific verb plus resource. It distinguishes itself from siblings like get_app and list_my_apps by limiting scope to public catalog and mentioning Aurora version defaults.

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 this is for discovery in the public catalog, with filtering by category or author and pagination, but it does not explicitly state when to choose it over alternatives like list_author_apps or list_categories. Some exclusion guidance would improve selection accuracy, but the public scope does narrow the use case.

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

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

Annotations only mark this as destructive/non-idempotent, while the description adds critical behavioral detail: description/category are shared APP fields affecting all releases; other attributes are preserved; exact user confirmation and unchanged state are required; and uncertain outcomes are never automatically retried. This gives an agent the safety-relevant 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?

The description is composed of short, purposeful sentences, each adding a distinct constraint: core action, shared-field side effect, preserved attributes, preconditions, RPM scope, and retry policy. The primary action is front-loaded, and there is no redundant 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 an output schema present, return values do not need to be described. The description covers field semantics, cross-release side effects, preserved data, preconditions, non-idempotency, and the binary/RPM limitation, making the tool safe and callable by an agent. The only slight ambiguity is the exact mechanics of 'user form confirmation', but the requirement itself is clearly disclosed.

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 explicitly names description, category_id, and release_notes as the editable fields, identifies version_id as the target version, and implies app_id through the 'shared APP fields affecting all releases' statement. It does not formally enumerate every parameter, but an agent can map the schema properties from the textual clues.

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 first sentence states a specific verb ('Change'), the exact editable fields ('plain-text description, category_id and/or release_notes'), and the target scope ('owned version_id'). It clearly differentiates this from sibling tools by limiting it to metadata changes and explicitly excluding RPM replacement.

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 clear usage context: it applies only to owned versions, requires exact user form confirmation, and requires an unchanged state. It also states what the tool does not do ('Does not replace RPMs'), but it does not explicitly name an alternative sibling tool for RPM replacement, so the routing guidance is strong but not fully 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 signal mutating/destructive behavior, and the description adds substantial behavioral context: exact user form confirmation, byte rechecking, duplicate rejection, 100,000,000-byte limit, no signature/SDK verification, server-controlled publication status, and a no-auto-retry rule. This goes well beyond the structured hints and provides practical operational guidance.

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 dense but every sentence adds meaningful constraint or behavior. It front-loads the core action and then efficiently lists critical rules and caveats without redundant phrasing.

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 output schema exists and annotations cover safety, the description supplies the missing operational context: file paths, ownership, byte limits, verification behavior, retry policy, and publication control. An agent has enough information to invoke this tool correctly and avoid unsafe 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It clarifies rpm32_path/rpm64_path as absolute-path ARM RPMs, app_id as an existing caller-owned app, and hints at duplicate version/OS constraints, but it does not explain release_notes or explicitly map aurora_versions to Aurora OS version targets. Partial compensation, not complete.

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

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

States a specific verb and resource: uploads ARM RPMs as a new release of an existing caller-owned app. It clearly differentiates from siblings by emphasizing 'NEW release' and 'existing caller-owned app', so an agent can tell it apart from create_app, update_my_app_version, or prepare_release.

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: for adding a new release to an existing owned app, with explicit constraints like one/two absolute-path RPMs and server-determined review status. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would not confuse it with scheduling, preparing, or updating metadata.

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