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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds useful scope: clear:true deletes all alerts and ignores ids. It does not add permissions or reversibility details, but it meaningfully clarifies the destructive path beyond the annotation flag.

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

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

Two compact sentences, front-loaded with the primary operation and immediately followed by the destructive alternative. There is no filler or repetition.

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

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

For a simple two-parameter mutation tool with full schema coverage and rich annotations, the description covers both invocation modes and the destructive exception. No output schema exists, but no return-value contract is 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 description coverage is 100%, and the schema already documents that ids defaults to all and clear ignores ids. The description restates that behavior clearly but adds no syntax or format details beyond the structured 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 names a specific verb and resource: mark rank alerts as read, then clearly distinguishes the alternate clear:true deletion mode. An agent can understand both operations and their difference without inspecting 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 explains the key usage branches: supply ids to target specific alerts, omit ids to mark all read, or set clear:true to delete all instead. It does not explicitly name list_rank_alerts as a read-only alternative, but the mutation 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 readOnly=false, idempotent=false, openWorld=true, so the bar is lower; the description still adds real behavioral context beyond them — that the listing import and keyword seeding run asynchronously in the background and only surface in get_overview on completion. It does not mention duplicate/re-add behavior, which is notable given idempotentHint=false, nor auth/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?

Three sentences, each doing distinct work: what it creates, what inputs it accepts plus where to get them, and what happens afterwards. Front-loaded with the core action; zero 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 an 8-parameter creation tool with no output schema, the description covers creation semantics, input sourcing, and the async completion signal. It leaves out failure/duplicate handling and whether a job id is returned, which an agent calling a non-idempotent background job could use.

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 every field including ai, brief, markets, folderId and mainLocale is already documented in the schema; the description adds only the identifier-form summary already present in the 'app' field. Baseline 3 applies where the schema does the heavy lifting and the prose adds no new parameter semantics.

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

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

Specific verb+resource: 'Start tracking an app as a project', with an explicit scope split ('your own app (kind mine) or a competitor') and accepted identifier forms. It is clearly distinguishable from neighbors like add_console_apps or link_released_app because it creates a tracking project rather than a console listing.

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?

Names the prerequisite path explicitly: 'find it with search_store', and tells the agent what to check afterwards ('the new project appears in get_overview when the job finishes'). It stops short of saying when NOT to use it (e.g., versus add_console_apps or link_released_app), so no 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 it a non-read-only, non-destructive, open-world write, so the safety bar is lower; the description still adds real value by disclosing that it is a bulk operation over all visible apps and that already-tracked apps are skipped. It omits failure behavior and rate/scale expectations, keeping it short of a 5.

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

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

One front-loaded sentence: the action and scope come first, with the skip behavior parenthesized as a secondary detail. No filler and 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 param, full schema coverage, annotations present and no output schema, the description covers what the tool acts on and how it treats existing projects. Missing only the auth/prerequisite statement and any indication of what is created per app, which keeps it from a 5.

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 'store' param already carries an enum with per-value meanings, so the schema does the heavy lifting. The description only echoes 'for a store' without adding format or effect details 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?

States a specific verb ('Track') and resource (every app visible in the connected developer console account) scoped to a store, so the agent knows exactly what the call does. It does not explicitly contrast with the near-siblings list_console_apps or add_app, which would be needed for a 5.

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

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

The phrase 'connected developer console account(s)' implies the connect_console prerequisite, but the description never states it as a requirement nor names alternatives such as list_console_apps (read-only inspection) or add_app (single manual add). When-not guidance is absent, leaving selection between siblings to inference.

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

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

Annotations already declare it is a non-read-only, non-idempotent, non-destructive write. The description adds real context beyond them: localize=true triggers an AI translation across every tracked market, and new keywords start with no ranks until run_rank_check. It stays silent on duplicate handling and on what the response contains, which matters for a non-idempotent mutation.

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 compact sentences, front-loaded with the action, then the section enum, then localize, then the rank post-condition. Dense and purposeful, though the nested parentheticals in the section sentence slow a first read 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?

For a 4-parameter write tool with full schema coverage and annotations, the description covers the main behavioral consequences (AI translation side effect, ranks not yet present). Missing only the return payload and duplicate-keyword behavior, which leaves a small gap for an agent deciding how to confirm success.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining what each enum value means in domain terms and by spelling out the localize semantics (translate per market vs. same phrase everywhere). Only projectId and the 100-item cap are left to 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?

States a specific verb and resource ("Add one or more keywords ... to a project") plus what a keyword is ("search phrases"). The action is unambiguous against siblings like remove_keywords or edit_keyword, though none are named explicitly.

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

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

Explains the choice between the two section values ('listing' = current targets, 'idea' = candidates to evaluate) and clarifies the localize default and effect. It also points to the follow-up tool (run_rank_check) needed for ranks, which is useful routing guidance, but it never states when not to use this tool versus suggest_keywords.

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 non-read-only, idempotent and non-destructive, and the description adds real context beyond them: already applied or dismissed changes are silently skipped (explaining the idempotency), and omitting changeIds applies every proposed change — a meaningful blast-radius warning. It does not say what the response contains or whether an apply can be undone.

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 action and the id source, then the skip rule, then the safety caveat. No filler and no repetition of the title.

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

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

For a 3-parameter mutation with full schema coverage and no output schema, the description covers scope, defaults, and skip semantics well. It leaves the post-apply return value unaddressed, which matters slightly since there is no output schema to fall back on.

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

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

Schema coverage is 100%, so the schema already documents all three fields including 'default: all proposed'. The description adds only the id example format and the 'still-proposed' qualifier on the default, which is marginal value over structured data — 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 ('Apply changes the assistant proposed in one of its messages') and ties the ids back to get_assistant_thread, so an agent knows exactly which objects this operates on. The clause about skipped applied/dismissed changes implicitly separates it from dismiss_assistant_changes.

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 operational context: omit changeIds for all still-proposed changes, and 'Only apply what the owner agreed to' sets the human-in-the-loop precondition. It never names dismiss_assistant_changes as the counterpart for rejecting proposals, so the alternative route is left 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?

Annotations declare non-read-only, non-destructive, non-idempotent, open-world, but the description adds the crucial behavioral facts: it is a background job, it mutates nothing itself, and results must be polled via wait_for_jobs then get_assistant_thread. This is exactly the context annotations cannot convey.

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

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

Three tight sentences, front-loaded with the action, then the propose-only constraint, then the follow-up workflow. No filler; every clause carries operational meaning.

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

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

No output schema exists, and the description compensates by explaining that the reply is asynchronous and must be fetched with get_assistant_thread after wait_for_jobs. Combined with the propose/apply/dismiss lifecycle, an agent has everything needed to call and follow up 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%, so all four parameters (including the ai provider enum and scope enum) are already documented in the schema. The description only echoes the keywords/optimizer scope distinction and adds no format or constraint detail beyond it, 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 ('Send a message to the in-app ASO assistant for a project') and scopes it to keywords or optimizer conversations. An agent can distinguish it from siblings like get_assistant_thread or apply_assistant_changes 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?

Explicitly says the tool only PROPOSES changes and applies nothing, instructs the agent to review with the owner, and names the follow-up tools (apply_assistant_changes, dismiss_assistant_changes). It also gives the retrieval path: read the reply with get_assistant_thread after wait_for_jobs.

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-readonly, open-world, non-idempotent but non-destructive mutation, so the safety profile is covered. The description adds real value beyond that: it discloses the AI-provider prerequisite and the two-stage behavior (keyword proposal from the brief, then market checks), which an agent cannot infer from annotations. It omits cost/latency implications of the AI step and what is created, keeping it at 4.

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

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

One sentence (plus a short prerequisite clause) with the action, scope, and mechanism front-loaded. Every clause carries information an agent needs; nothing is 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 three-parameter mutation with full schema coverage and no output schema, the definition covers purpose, selection condition, and the AI prerequisite. The only gap is that it doesn't indicate what the agent gets back (a new project id? a keyword list needing review?), which would help the follow-up call.

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 brief, store, and markets are already fully documented in the schema. The description reinforces brief and markets at a high level but adds no format, defaults, or constraints beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ("Create a brainstorm project") and pins the scope with "for an app that does not exist yet," which implicitly separates it from add_app/link_released_app. The follow-on clause explains the mechanism (AI proposes keywords from a brief, checks them in chosen markets), so an agent knows exactly what the call produces.

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

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

The phrase "for an app that does not exist yet" gives a clear selection condition versus project-creation siblings, and "Requires a ready AI provider" states a prerequisite. It stops short of naming an explicit alternative or when-not-to-use case, so it lands just below the top band.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety and repeat-call semantics are covered. The description adds only that the target is conversation history; it doesn't say whether pending assistant changes are also discarded or whether the action is reversible, which is the kind of detail that matters for a destructive op.

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 zero filler. It is efficient, though the brevity leaves no room for the scoping caveat an agent would benefit 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 one-parameter destructive tool with full annotation coverage, the definition is minimally adequate. It stops short of specifying scope (all threads vs. all messages of one thread) and what happens to related assistant state, which an agent needs before invoking a delete.

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

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

Only one parameter and schema coverage is 100%, with the schema itself noting the id comes from get_overview. The description adds no format or sourcing detail beyond that, 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: 'Delete the assistant conversation history of a project.' This is clearly distinguishable from clear_jobs (jobs) and get_assistant_thread (read a thread), though it never names those siblings explicitly.

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

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

No guidance on when to use this versus get_assistant_thread, clear_jobs, or any other cleanup tool, and no stated preconditions or confirmation expectations. The agent must infer usage entirely from the verb.

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 flag destructiveHint=true and idempotentHint=true, and the description adds real value on top by stating exactly what is deleted (finished, failed, stopped jobs) and what survives (queued/running jobs and their results such as rankings and options). It stops short of saying removal is irreversible or that no data beyond the list entry is lost.

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

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

Two short sentences with the destructive scope front-loaded and the safety clarification immediately after; every clause carries actionable information and nothing is repeated from the annotations.

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

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

For a zero-parameter, no-output-schema mutation, the description covers what is affected and what is untouched, which is the key risk an agent must weigh. A note on irreversibility or confirmation requirements would make it fully complete.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly avoids inventing filtering options.

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

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

The description gives a specific verb and resource ("Remove finished, failed and stopped jobs from the job list") with an explicit scope qualifier. It implicitly differentiates from stop_job/wait_for_jobs by stating that queued and running jobs are kept, though it never names a sibling outright.

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 is only implied: an agent must infer that this is the cleanup action for terminal-state jobs and that stop_job should be used instead when a job is still running. No explicit when-to-use or when-not-to-use statement is present.

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 annotations, the description discloses critical behavior: the bridge reads secrets locally, the app stores them in the OS keychain, and credentials are never returned. It also states file-location and extension restrictions, which an agent must know before calling the tool.

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

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

The description is front-loaded with the core action and has no wasted sentences. The long parenthetical about allowed file paths and extensions is dense but earns its place as operational constraint.

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 credential-connection tool with no output schema, the description covers what is stored, where it is stored, that credentials are not returned, and how to pass secrets safely. It stops short of explaining whether the connection is validated immediately or whether test_console should follow, but it is otherwise 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: agents should pass file paths rather than inline secrets, and those files must be .p8/.pem/.json/.txt in the owner's Downloads, Desktop, or Documents folder. It also groups parameters by store (apple vs. google), which helps selection.

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

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

The description names a specific verb and resource: connecting an App Store Connect API key or Google Play service account. It distinguishes the two auth paths and states the effect (credentials stored in the OS keychain), so an agent can tell exactly what this tool does.

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

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

It says the tool is needed for console apps, publishing, and own-app metadata, which gives clear context for when to call it. It does not name alternatives such as test_console or disconnect_console, nor does it state when not to use this tool, so it falls short of the explicit when/when-not pattern.

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?

Adds real context beyond annotations: secrets are stored in the OS keychain and never returned, which tells the agent credential handling is safe to pass in. Annotations already cover the safety profile (non-destructive, open world), but the description does not disclose what happens on repeat calls despite idempotentHint=false.

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

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

A single dense sentence with the source list and the sequencing directive up front; little waste. The credential lists make it long, but each clause maps to a real parameter group.

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 15-parameter, no-output-schema tool, it covers source selection, credential handling and the follow-up call well. Gaps remain on the `store` parameter and on what happens if a source is already connected.

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 per-parameter meaning is already documented, but the description adds the grouping of which parameters belong to which source and reinforces preferring paths over inline PEM. It does not cover the `store` enum parameter at all.

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 ("Connect a source of REAL keyword popularity") and enumerates the three supported source types with their credential sets. This makes it clearly distinct from siblings like disconnect_popularity and fetch_popularity.

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 precondition (choose apple_ads, google_ads_planner or imported), a preference ("Prefer file paths for keys") and an explicit next step ("Then call fetch_popularity"). It does not mention when not to use it or reference disconnect_popularity / get_popularity_status as alternatives.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety bar is lower, yet the description still adds value by disclosing exactly what is destroyed: the account plus its stored keychain credential. The confirmation instruction adds a permission-related behavioral cue; only rate-limit/irreversibility specifics are absent.

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

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

Two short sentences, zero filler, with the destructive scope stated first and the confirmation requirement immediately after. Every clause carries information.

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

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

For a single-parameter destructive tool with rich annotations and no output schema, the description covers purpose, destruction scope, and the confirmation prerequisite. Only a note on irreversibility or recovery (whether the key can be re-added via connect_console) is missing.

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

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

Schema description coverage is 100% for the single accountId parameter, so the schema fully documents it (type, length bounds, meaning). The description adds no extra semantics about the identifier, so the baseline 3 applies.

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

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

Uses a specific verb ('Remove') plus resource ('console account') and adds the side effect of deleting the stored key from the keychain. It is clearly the inverse of the sibling connect_console, but it never names that sibling explicitly, so differentiation is implied rather than stated.

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?

'Ask the owner first' gives a minimal pre-call confirmation rule, which is genuine guidance for a destructive action. However, there is no statement of when to prefer alternatives (e.g., merely re-authenticating vs. fully disconnecting) or any exclusion conditions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description isn't carrying the safety profile alone. It still adds value by naming what is destroyed (stored credentials) and requiring owner sign-off, though it doesn't say whether previously fetched popularity/volume data survives or whether reconnection is possible.

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

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

Two sentences, no filler, and the destructive action is front-loaded ahead of the confirmation caveat. Nothing redundant with the title.

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

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

For a one-parameter mutation with full annotation coverage and no output schema, the description covers action, destruction target, and authorization. The remaining gap is whether the underlying popularity data is retained after credential deletion, which an agent might reasonably need to know.

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

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

Schema coverage is 100% and the single parameter is a fully enumerated string, so the schema does the work. The description adds no meaning about how 'source' maps to the disconnect action beyond what the enum already declares, which is the baseline case.

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 ('Disconnect') and resource ('popularity source') plus the concrete side effect ('delete its stored credentials'). This cleanly separates it from the sibling connect_popularity and from read-only siblings like get_popularity_status or fetch_popularity.

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?

'Ask the owner first' gives a real prerequisite, which implies this is a deliberate teardown action rather than routine. However, it never states when-not-to-use it as opposed to leaving the source connected, and doesn't point at connect_popularity for the inverse operation.

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 indicate this is a non-destructive, idempotent mutation. The description adds useful behavioral context by stating that nothing in the project changes and that omitting changeIds dismisses every still-proposed change.

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

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

The description is a single, front-loaded sentence with no wasted language. It communicates the core action and the key default behavior efficiently.

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 three-parameter tool with full schema descriptions and rich annotations, the description covers the essential action and non-impact on the project. It omits explicit routing between assistant tools, but otherwise provides enough context 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 100%, so the parameters are already well documented. The description reinforces the default behavior for changeIds but does not add notably deeper parameter semantics beyond what the schema provides.

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

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

It uses a specific verb and resource: mark assistant-proposed changes as dismissed. The scope is clear, but it does not explicitly contrast with the sibling apply_assistant_changes tool, so sibling differentiation is implied rather than stated.

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 use through wording like 'dismiss' and clarifies that omitting changeIds dismisses all still-proposed changes. However, it does not explicitly state when to use this instead of apply_assistant_changes or other assistant-related 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, destructiveHint=false, and idempotentHint=true, so the mutation profile is covered. The description adds genuinely new behavioral context: hiding is non-destructive in effect (tracking continues, board visibility changes). It does not mention permissions or what happens to historical rank data on rename.

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

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

One sentence, front-loaded with the primary action and immediately followed by the semantic clarification of the hidden state. 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 3-parameter mutation with full schema coverage, good annotations, and no output schema, the description covers purpose and the key state semantics. Minor gap: it does not say whether the label must be unique or whether renaming affects existing rank history.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema's terse 'true = hide, false = show again' by explaining the tracked-but-not-on-board consequence. The 'and/or' phrasing also clarifies that label and hidden can be combined in one call.

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

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

States a specific verb+resource (rename a keyword, hide/unhide it) and immediately disambiguates the 'hidden' state as staying tracked but off the active board. An agent can distinguish it from remove_keywords, add_keywords, and localize_keyword 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 parenthetical 'hidden keywords stay tracked but leave the active board' implicitly contrasts hiding with deletion, which is the main alternative an agent would weigh (remove_keywords). However, no sibling tool is named explicitly and no when-not-to-use condition 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 declare readOnlyHint=false, destructiveHint=false and idempotent=true, and the description correctly explains where the non-read side effect lives: writing into the app's exports folder, and that fastlane always emits a zip of deliver/supply metadata. That is real added context, though it doesn't say what the exports folder path is or whether an existing file is overwritten.

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 primary behavior (default = return content, truncated) front-loaded ahead of the saveToFile and fastlane exceptions. The parenthetical '(cut at maxChars)' and 'format fastlane (what optimizer only)' are terse but readable; no sentence is 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 five-parameter export tool with no output schema, the description covers both modes, the truncation limit interaction, and the fastlane special case. Remaining gaps are minor: the response shape when returning content, overwrite behavior, and where exactly the exports folder lives.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the interaction between maxChars truncation and the default return path, and by adding a constraint the schema does not encode (fastlane is only valid with what=optimizer).

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 gives a specific verb (export) and the exact resource set the enum constrains: board, rank history, optimizer drafts, plus the output formats. This clearly separates it from read-oriented siblings like get_project_board or get_optimizer, 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?

It states the branch conditions for the two modes — default returns content, saveToFile:true writes to the exports folder — and flags that format=fastlane only applies to what=optimizer. It stops short of saying when to prefer an export over simply reading the board via get_project_board.

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 annotations already declare openWorldHint=true, readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds materially useful context: it identifies the external data source and the requirement for a connected source, which explains why the operation is open-world and non-idempotent. It does not disclose quota consumption, rate limits, or failure behavior, so it is strong but not complete.

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 front-loaded sentences with no filler. Every clause contributes routing information, prerequisite information, or scope clarification.

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 two parameters, complete schema coverage, rich annotations, and no output schema, the description covers purpose, prerequisite, and sibling differentiation well. It still leaves minor gaps around return format and external-source cost or rate-limit behavior, but an agent has enough to select and invoke the tool 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 description coverage is 100%, so projectId and markets are already fully documented in the schema. The description adds context that the popularity is for the project's keywords, but it does not add syntax or behavioral meaning for the markets parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb, 'Pull', and a specific resource, 'REAL search popularity for the project's keywords', and names the external sources. It explicitly distinguishes this tool from rank checks and ASOMaster's estimates, so an agent can identify its role 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 states the prerequisite clearly: a connected source, pointing to get_popularity_status, and it distinguishes this from rank checks and estimates. It does not explicitly mention connect_popularity as the fallback or compare directly with siblings like popular_searches or get_volume_calibration, 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that by disclosing what the response actually contains (installed/signed-in/ready flags, current model, next setup step), which is valuable since there is no output schema.

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

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

A single sentence with the resource front-loaded and the returned fields enumerated after the colon. No filler, though the consumer list ('brainstorming, suggestions, the optimizer and the assistant') is slightly verbose for the value it adds.

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 burden of explaining return values, and it does so concretely by naming the three status states, the current model, and the next setup step. That is sufficient for an agent to call and interpret this tool correctly; only explicit routing versus sibling AI tools 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 tool takes zero parameters, so the baseline is 4. The description correctly describes a parameterless inspection call and does not invent or omit any input semantics.

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

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

States a specific resource (status of the local AI providers) and enumerates the exact states reported: installed / signed in / ready, current model, and next setup step. It distinguishes itself from the mutating siblings (set_ai_provider, test_ai_provider) by being purely a status read, 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?

Usage is only implied through the mention of consuming features (brainstorming, suggestions, optimizer, assistant) and the 'next setup step when not ready' hint, which suggests diagnosing configuration problems. There is no explicit statement of when to call this versus test_ai_provider or set_ai_provider, and no 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine behavioral facts the annotations cannot: Google Play returns an empty list because its page has no reliable dates, ids absent from the response mean the app is not in that store, and a 50-id ceiling applies.

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 no filler; the field list is front-loaded and the caveats (empty Play result, missing ids, id cap) follow. The leading fragment 'For App Store ids (e.g. competitors from get_board) in one store:' is slightly elliptical but still efficient.

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

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

With no output schema, the description carries the return-shape burden and does so by naming every returned field. Combined with the empty-list rule, missing-id rule and id ceiling, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds provenance for 'ids' (competitors from get_board) and restates the 50-id cap that constrains the array. It gives no extra semantics for 'country' beyond the schema's own ISO code explanation.

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 enumerates exactly what is returned (first release date, current version date, version, price, rating count, ratings per day) for a specific resource (App Store ids in one store), which is far more than the title 'Competitor facts' conveys. It does not, however, contrast itself with nearby siblings such as get_ratings or get_overview, so the agent must infer the boundary itself.

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 tells the agent where the ids come from ('competitors from get_board'), that the tool is per-store, and that Google Play yields an empty list — effectively a when-not condition. It also gives interpretive guidance ('a fresh update and high ratings/day mean an active rival'). It stops short of naming an alternative tool for Google Play data or for rating history.

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 annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world operation. The description adds useful behavioral context by explaining that results include mentioned keywords and proposed changes with their statuses, though it does not describe empty-thread behavior or ordering guarantees.

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

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

The definition is a single front-loaded sentence that conveys the resource, scope, and return contents without filler. Every clause adds useful information.

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

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

For a simple read-only retrieval tool with full schema coverage and clear annotations, the description is complete enough. It explains the returned conversation content and change statuses, which compensates for the absence of an 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?

Schema description coverage is 100%, so parameter meaning is primarily carried by the schema. The description reinforces the meaning of scope as keywords or optimizer scope and ties results to a project, but it does not add further detail about lastMessages or the meaning of individual statuses.

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 that this retrieves recent messages from the ASO assistant conversation for a project, with keywords or optimizer scope. It is specific about the resource and contents, but it does not explicitly distinguish itself from related assistants such as ask_assistant, apply_assistant_changes, or dismiss_assistant_changes.

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 implied use case is inspecting the current assistant conversation and the status of proposed changes. However, there is no explicit guidance about when to call this versus ask_assistant, apply_assistant_changes, dismiss_assistant_changes, or clear_assistant.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for disclosing return semantics instead: the weightings, the verdict enumeration, the four takeaway categories with their trigger conditions, and demand history. It stops short of stating freshness/caching or computation cost, which would complete the picture.

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?

Front-loaded with the score definition, which is good, but the body is one sprawling sentence dense with nested parentheticals that make the takeaway taxonomy hard to scan. Nearly all content is substantive, yet a bulleted or clause-separated structure would cost nothing.

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 full burden of describing returns, and it does so thoroughly — component scores, verdict labels, takeaway types, and history. Remaining gaps (data freshness, whether the audit recomputes on call) are modest.

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

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

Only one parameter (projectId), and the schema already documents it at 100% coverage including provenance ('from get_overview'). The description adds nothing about the parameter, so the baseline 3 for a fully-covered schema 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?

Opens with a specific verb-and-resource framing ('Where the app stands, 0-100, per tracked market and overall') and enumerates the concrete sub-scores it returns (rankings, listing, competition, verdict). It is clearly a read-only audit/report tool, distinct from get_overview or get_optimizer, 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?

The closing sentence 'Use it to pick the next optimizer or keyword step' implies the decision context (choosing between optimizer vs keyword work), which is useful routing. But there are no exclusions, no prerequisites, and no named alternative for the 'I just want a quick summary' case (get_overview).

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-destructiveness, so the safety profile is covered. The description adds the useful caveat that the editable version may not exist and clarifies what data is returned, but it does not describe output structure or null behavior in detail.

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 definition is a single dense sentence with no wasted text, and the core subject is front-loaded. It is slightly fragment-like rather than structured as a clear action statement.

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

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

For a simple read-only tool with rich annotations and a fully described single parameter, the description covers both returned conceptual values. It does not specify the exact response shape, but with no output schema this is a minor gap.

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

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

Schema description coverage is 100%, and projectId is explicitly documented as coming from get_overview. The description adds no additional meaning about the parameter, so the schema fully carries this dimension.

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

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

The description names the specific resource and two concrete outputs: the editable app version and the suggested publishing version string. It is a noun phrase rather than an explicit verb, and it does not distinguish itself from related siblings like get_publish_preview.

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

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

There is no explicit when-to-use guidance, prerequisites, or comparison with alternative tools. The publishing context hints at usage, but an agent must infer when this is preferable to get_publish_preview or other version-related 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 readOnly/idempotent/non-destructive, and the description adds a genuinely useful behavioral trait not in the annotations: descriptions are truncated unless full=true. It also explains that only one locale's draft comes back in full while others are status-only, which affects how much data the agent gets. It stops short of stating payload size or whether reading has side effects on job state.

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 opens with the verb and resource, then lists returns. Dense with parentheticals but each item maps to real output; minor trimming possible in the enumeration.

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 conveying the return shape and does so item by item, and annotations cover the safety profile. Missing only secondary details such as payload size or behaviour when no options have been generated yet.

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

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

Schema coverage is 100% and the schema already documents full ('Return full descriptions') and locale ('Only show this locale's draft in full; others are listed by status'). The closing sentence largely restates the `full` flag, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Listing optimizer state for a project') and then enumerates exactly what the state comprises: step, live listing, generated options with reach/difficulty, chosen option, core phrases, per-locale drafts. That inventory makes it clearly distinguishable from the mutating optimizer_* siblings and from get_overview.

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

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

Usage is only implied: the enumerated contents suggest you call it to inspect state before calling optimizer_choose/optimizer_save_option. There is no explicit when-to-use, no when-not, and no named alternative among the many optimizer_* siblings.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds real value by disclosing the breadth of the payload (projects, folders, jobs, settings, license, alerts), telling the agent this is a heavyweight dashboard read rather than a narrow query.

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?

Front-loaded with the routing instruction 'Start here,' followed by a single dense enumeration sentence. The parenthetical field list is long but each item signals real payload content; no sentence is wasted.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly (project fields, counts, audit step, jobs, license, alerts). Only gap is the absence of any note on the optional filters' effect on the returned payload.

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

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

Schema description coverage is 100% and all three filters (kind, store, folderId) are fully documented with enums in the schema. The description only implicitly suggests the unfiltered 'every tracked project' default and adds no syntax or interaction detail beyond the schema, 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 concrete verb ('Lists') and enumerates the resources returned: projects with specific fields, folders, running/finished jobs, settings, license state and unread rank alerts. This clearly separates it from the many single-resource siblings like list_rank_alerts or get_project_board.

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?

'Start here' plus 'Use the ids it returns with every other tool' gives explicit entry-point guidance and explains how the output feeds the rest of the toolset. It does not name a competing sibling or state when not to use it, so it stops short of full alternatives coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: it reveals that credentials are never returned (a security/privacy guarantee an agent needs when deciding what to report) and that each source carries a store scope and last-fetch timestamp.

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

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

Two sentences, zero filler, and the core answer (which sources are connected) is front-loaded before the two qualifiers. The 'REAL' emphasis cheaply signals that placeholder/unconfigured sources are excluded.

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 parameters, no output schema, and full annotation coverage, the description carries the remaining burden and does so: it enumerates the source kinds and the fields returned (store, last fetch). A slightly fuller account of the response shape (e.g. whether disconnected sources appear with a null timestamp) would close the last 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 the schema carries no semantic load the description must compensate for. The description spends its words on the return shape instead, which is the right allocation.

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 the specific resource (connected popularity sources) and enumerates the concrete source types (Apple Ads, Google Ads Keyword Planner, imported files), plus what metadata is returned (store, last fetch time). It reads clearly as a status/introspection read, distinguishing it from the sibling mutators connect_popularity, disconnect_popularity and fetch_popularity, though it never names those alternatives explicitly.

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

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

The framing ('which ... are connected') implies the use case: inspecting source state, likely before fetch_popularity or connect_popularity. But there is no explicit when-to-use statement, no exclusion, and no pointer to a sibling alternative, so the routing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the conditional behavior it discloses: popularity is only real when a provider is connected, hidden keywords are excluded unless section=hidden/all, and only the main market is returned when more than 4 markets are tracked. Those are genuine caveats an agent would otherwise miss; only pagination/truncation behavior is left unstated.

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 return-shape summary is front-loaded and the conditional rules follow, with no filler sentences. It is dense and reads as a long run-on clause chain, which slightly hurts scanability but nothing is 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 no output schema, the description carries the burden of explaining return values and does so field by field, including the estVol/estDiff vs pop distinction and competitor inclusion. It is nearly complete; only result-size/pagination expectations are unaddressed.

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

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

Schema coverage is 100% and the schema already documents every parameter, including defaults for markets, section, sort and limit. The description restates the markets and hidden-section defaults rather than adding new syntax or semantics, so it sits at the baseline.

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

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

The description states a specific verb and resource ('Keyword x market grid for one project') plus the exact result shape (rank, estVol/estDiff, pop, verdict, opportunity, top competitors). That is far more than the title and lets an agent tell this apart from get_term_detail (single term) or get_overview 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?

There is no explicit 'use this when / not when' guidance and no sibling is named as an alternative. Usage is only implied by the described content (a board-level view of all keywords in a project), and the market/section rules read as behavior rather than selection advice.

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/openWorldHint annotations, it discloses the external network read and, crucially, a degradation path — source is "console (fresh read) or stored (no console answered)" — so the agent knows results may be stale. It also sketches the return shape (from→to, isNew, unchanged), though it does not mention latency or per-language failure modes.

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 ordering constraint is front-loaded in the first clause and every subsequent clause carries real information (change format, isNew, unchanged, source). The single run-on sentence is dense but not padded.

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

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

There is no output schema, so the description must carry the return semantics — and it does, enumerating the per-language change records, the isNew flag, the unchanged set, and the source discriminator. Combined with read-only annotations and a fully documented single parameter, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single projectId parameter already carries its own description pointing at get_overview. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource — reads the live listing from App Store Connect / Play Console and reports each field that publish_listing would change — and explicitly anchors itself relative to the publish_listing sibling. An agent can distinguish it from get_overview or publish_listing without opening a schema.

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

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

"Before publish_listing" plus "Tell the owner what changes before publishing" gives an unambiguous trigger condition and names the sibling it precedes. No explicit when-not-to-use case, but the sequencing constraint is clear enough to route correctly.

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 handle safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real context beyond them: data freshness/provenance (recorded after each rank check), and differing granularity between sources (App Store per storefront vs Google Play global). It does not address volume, ordering, or a cap on returned daily points, which keeps it from 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?

A single dense sentence that front-loads the resource and then the returned measures; every clause carries information. It is slightly run-on with stacked parentheticals, but not padded.

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

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

There is no output schema, so the description correctly carries the burden of describing the return shape (latest values, newRatings, ratingChange, daily points) and the per-market/per-storefront breakdown. Missing only minor operational detail such as result ordering or how the daily series is bounded.

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% with only two parameters, so the baseline is 3. The description reinforces that `days` is a lookback range and that results are broken out per market, but adds no format or constraint detail (e.g. the 365-day cap) 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 names the exact resource (average rating and rating count per market over a date range) and enumerates the returned measures (latest values, newRatings, ratingChange, daily points). No sibling tool covers ratings, so the agent can distinguish it cleanly from get_overview, list_rank_alerts, popular_searches and other read 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 the framing ('recorded after each rank check', 'last days', 'per market'), which tells the agent what the data represents but not explicitly when to pick this over another source. With no true sibling for ratings data, the absence of explicit routing guidance is a minor but real gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the returned state and explaining that checks such as missing images, heading limits, stale translations, and low contrast block export and upload.

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 resource and its components, then closes with actionable routing to sibling tools and the app. It is dense but efficient; the parenthetical checks are informative rather than 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?

Given the lack of an output schema, the description does a good job enumerating what the tool returns and what the checks mean. It does not need to explain return formatting further, and the single required parameter is fully documented in the schema.

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

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

There is only one parameter, projectId, and schema description coverage is 100%, with the schema itself explaining that it comes from get_overview. The description does not add further meaning about the parameter, 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 states a specific resource and scope: the project's screenshot design, including slides, theme, headings, render status, and checks. It also distinguishes this read tool from the editing siblings screenshots_write_headings and screenshots_translate, so an agent can identify its role 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 routes heading edits to screenshots_write_headings / screenshots_translate and says images, rendering, export, and upload happen in the app. That gives clear usage context and alternatives, though it does not explicitly say when to call this tool versus get_overview or other project-state 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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuine value by disclosing the return payload groups (current cell, daily history, ranking apps including title/subtitle match flags), which matters because there is no output schema. It does not mention truncation behavior or how history points relate to the requested ranges, but the core behavioral surface is described.

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 scope ('Everything about one keyword in one market') then lists the three returned payload groups. No filler, no restatement of the title, and every clause maps to something the tool actually returns.

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

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

With no output schema, the description correctly shoulders the burden of describing return content and does so at a useful granularity for a read-only detail endpoint. Minor gaps remain: it does not clarify how many history series are returned (rank vs. popularity separately) or how the response behaves when historyPoints or topApps are 0.

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%, with market format, defaults, and ranges all documented in the schema, so the baseline of 3 applies. The description reinforces the market scoping and that history is day-granular, but adds nothing about topApps or historyPoints semantics beyond what the schema already states.

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

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

States a specific resource and scope (one keyword in one market) and enumerates the exact payload: current cell metrics, daily rank/estimate history, and ranking apps with their fields. That enumeration cleanly separates it from get_project_board (which lists keywords) and search_store (which finds apps), without needing to name them.

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: an agent can infer this is the drill-down for a keyword surfaced elsewhere, reinforced by the schema noting keywordId comes from get_project_board. There is no explicit when-to-use statement, no when-not-to-use, and no guidance on when to prefer this over the board or app-level 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 establish read-only, idempotent, closed-world behavior. The description adds meaningful behavioral detail beyond that: a null Spearman result under 10 pairs, value ranges of -1..1 and 0-100, and the band-agreement definition. It does not discuss performance or cost, but the diagnostic constraints are well disclosed.

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-loads the core purpose before listing metrics and then usage. It is somewhat dense with statistical terminology in a single sentence, but every clause contributes useful information and nothing is 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?

There is no output schema, so the description carries the responsibility of explaining return values, which it does thoroughly by naming and defining each metric. Combined with rich annotations and zero parameters, an agent has everything needed to call the tool and interpret its results.

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

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

The tool has zero parameters, so there is no parameter semantics to clarify. The baseline for zero-parameter tools is 4, and the description correctly focuses on output metrics instead of inventing parameter guidance.

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 that this tool measures how well estimated volume tracks real popularity, and it enumerates the exact metrics produced (pairs, Spearman correlation, meanAbsError, bandAgreement). It is specific enough to distinguish this diagnostic from siblings like get_popularity_status or fetch_popularity, though it does not explicitly name an 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 final sentence gives clear usage context: 'Use it to judge how far to trust estimates where real popularity is missing.' That tells the agent when the tool is appropriate. It does not state when not to use it or name a specific alternative, so it falls short of the top score.

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 that this is a non-read-only, open-world, non-destructive, non-idempotent operation. The description adds useful behavioral detail: allowed file locations, Astro database reading behavior, preview-only reporting, and that imports run as a background job. It does not explain how to track or retrieve the background job result, which is a notable remaining gap.

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

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

The description is dense but front-loaded and every sentence carries useful operational information. It could be easier to scan with structured formatting, but it avoids 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?

The description covers the import modes and key parameters well, but it does not return an output schema and only says 'Background job.' An agent still lacks guidance on what the import returns and how to wait for or inspect the job, which matters for a non-idempotent, open-world import operation.

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 all six parameters. The description still adds meaningful semantics beyond the schema for path omission with format astro, Astro import effects, previewOnly, and projectId/folderId behavior.

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

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

The description states a specific verb and resource: importing an Astro export or CSV of apps/keywords from a local path. It also distinguishes the Astro-database mode from ordinary file import and clarifies how imported data can become projects or join an existing project.

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

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

It gives clear conditional usage: path is required except with format astro, previewOnly only reports, and projectId vs folderId determines whether phrases join a project or apps become projects. It does not explicitly compare against sibling tools like add_keywords or export_data, but the import-specific context is strong.

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

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

Annotations only say non-read-only, open-world, non-idempotent, non-destructive. The description goes well beyond them: it discloses the post-mutation state (project becomes kind mine/competitor), that keywords and history are preserved, that the store listing name replaces the idea's name (an implicit rename side effect), and the two rejection conditions.

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: scenario, effects, failure modes, in that order. No filler and the usage trigger is front-loaded ahead of the 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?

There is no output schema, yet the description tells the agent what the resulting state looks like and what causes failure, which is everything needed to call a three-parameter mutation 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%, so all three parameters are already documented, and the description largely restates them (app id/package/URL, mine vs competitor). It adds only marginal framing — that projectId refers to a brainstorm project — 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: linking a brainstorm app idea (no store app yet) to its App Store id / Play package / store URL. This clearly distinguishes it from siblings like brainstorm_project, add_app, and update_project by naming the exact transition it performs.

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 opening clause gives a clear usage trigger ('An app idea ... is now published') and the closing sentence names explicit failure conditions ('Fails for projects that already have an app or when the app is already tracked'). It stops short of naming the alternative tool an agent should call when those preconditions fail, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the result is scoped to a single store and includes both the connected accounts and their visible apps with tracking status, which tells the agent what it will actually get back. It stops short of covering the no-console-connected case or auth prerequisites.

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 dense sentence with zero filler, front-loaded with the resource and immediately followed by the payload contents. Nothing is repeated from the title or schema.

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

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

With one enum parameter, full schema coverage, annotations, and no output schema, the description covers the essentials: what is listed, per which store, and the tracking flag. Minor gaps remain around behavior when no console account is connected, but 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?

Only one parameter, and the schema documents it fully with an enum and inline description. The description reinforces the per-store scoping but adds no syntax or behavior beyond what the schema already states, so the baseline of 3 applies.

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

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

Names a specific resource (connected developer console accounts for a store, plus the apps they can see) and adds the distinguishing payload detail of per-app tracked status. An agent can tell this is a read-only inventory of console connections rather than the act of connecting (connect_console) or adding apps (add_console_apps), though no sibling is named explicitly.

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

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

There is no explicit when-to-use or when-not statement and no named alternative. Usage is only implied by the content: the 'already tracked' flag suggests using this to check state before add_console_apps or to inspect what connect_console produced, but the agent must infer that.

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 closed-world scope, so the safety profile is fully covered. The description adds the useful detail that results carry a 0-10 potential score and per-store language/locale data, but says nothing about ordering, completeness, or whether the set varies by store beyond the enum.

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

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

One compact sentence with no filler, and the core resource leads. The list of returned fields is slightly compressed into a comma run that reads like a spec fragment rather than 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 two-parameter read tool with no output schema, the description supplies enough about the return shape (language, locales, score) for an agent to act. The missing piece is how these markets relate to the project-level market-setting siblings.

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 both parameters carry their own descriptions, including the store enum values, so the schema does the heavy lifting. The description adds no meaning for featuredOnly and only tangentially clarifies what a 'market id' is.

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 definition states the resource precisely — markets/countries available for a given store — and enumerates the returned fields (search language, listing locales, 0-10 potential score). It never names the related sibling set_project_markets, so an agent must infer the read-vs-write distinction from the name alone.

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

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

There is no explicit when-to-use statement, no prerequisites, and no mention of the counterpart tool set_project_markets that consumes these ids. 'Use the country codes as market ids' is a downstream hint about the output, not guidance on when to call this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the ordering trait ('newest first'); it does not mention pagination behavior, whether unreadOnly silently filters most alerts by default, or that the set is capped at the limit.

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

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

A single tight sentence with the resource front-loaded and the ordering note appended; no filler. It is slightly compressed to the point of omitting filter guidance, 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 three optional params, no output schema, and full annotation coverage, the description supplies what the structured fields do not: the shape of the returned alert (keyword, market, from -> to rank) and the default ordering. Only the default unread filtering and result-cap behavior are left implicit, which the schema partly covers.

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 limit, projectId, and unreadOnly are all documented in the schema, including the default of true for unreadOnly and the max of 500. The description adds no syntax or scoping nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Rank-change alerts raised by checks') and enumerates the payload fields (keyword, market, from -> to rank) plus the sort order. An agent can distinguish it from acknowledge_alerts, though the description does not name that 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?

Usage is only implied by the name and the phrase 'raised by checks'; there is no explicit when-to-use, no mention of when to prefer acknowledge_alerts or other listing tools, and no prerequisites. Adequate for an obvious read tool but leaves routing to inference.

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

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

Annotations already declare this as a safe read-only, idempotent, closed-world operation, so the burden is lower. The description adds meaningful context beyond the annotations: changes are captured only when a listing is re-read on every rank check, and results are newest-first with specific field semantics.

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 dense sentence that front-loads what the tool returns and then layers timing, ordering, and field breakdown. It is efficient, though the run-on structure with multiple parentheticals makes it slightly harder to scan than it could be.

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 input parameters and no output schema, the description carries the return-value explanation and does so adequately: it names the record fields and the capture cadence. Only the absence of any sibling/alternative routing keeps it from a 5.

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?

This tool has zero input parameters, so the baseline is 4. The description properly spends its words on output shape (app, locale, field, from -> to, read) rather than inventing parameter guidance that does not exist.

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 (name/subtitle changes of tracked rivals, kind competitor), plus ordering and returned fields. It implicitly separates itself from rank-alert tools by focusing on listing renames rather than rank movements, 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?

The closing line gives one actionable context — a rival renaming around a phrase is a cue to re-check that phrase — but there is no explicit when-to-use/when-not guidance and no named alternative among the many sibling list_* 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is already covered. The description adds genuinely new behavioral context: existing per-market phrases that were not manually overridden get replaced, which tells the agent exactly what state this mutation clobbers and what it preserves. It stops short of describing whether the AI call is synchronous, whether it consumes credits, or how failures surface, so it is 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?

A single dense sentence with the action front-loaded and the overwrite rule trailing as a qualifier; nothing is padded. The slightly awkward 'Have the AI' construction is the only blemish, not a structural problem.

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

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

With only two fully documented parameters and no output schema, the description covers the call itself adequately. But for an AI-backed, non-idempotent, open-world operation it omits whether the call blocks or enqueues a job, what is returned (results, job id, nothing), and what happens if no AI provider is configured — gaps an agent would hit on first 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% — both keywordId and markets are documented in the schema, including the ISO 3166-1 alpha-2 format and the default of all tracked markets. The description only restates the markets filter ('or the given markets') without adding format or edge-case semantics, 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 (translate), resource (keyword), and scope (each market or the given markets), so an agent knows exactly what the tool does. It never names the adjacent siblings set_market_phrase or optimizer_localize, so differentiation is left to inference, but the AI-driven keyword translation framing is clear enough to distinguish it in practice.

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 'Have the AI translate a keyword into the search language of each market' and the optional markets parameter is explained as a narrowing filter. However, there is no explicit when-to-use versus set_market_phrase (manual phrase setting) or optimizer_localize, and no stated prerequisites such as needing a configured AI provider.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds useful semantics — null folder means top level, and the move can position the project relative to another. It says nothing about permission requirements or side effects on ordering of neighbouring projects.

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 primary action first and the optional capability trailing; 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?

For a three-parameter, non-destructive, idempotent mutation with a fully documented schema and no output schema, the description covers the essential semantics. Only permission/prerequisite context is missing, which is minor at this complexity.

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

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

Schema description coverage is 100%, so both folderId's null semantics and beforeId's meaning are already documented in the schema; the description's parenthetical largely restates the folderId description. Baseline 3 applies — it adds no syntax, ID-format, or constraint detail 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?

States a specific verb and resource ('Move a project') plus the target container ('into a folder'), so the operation is unambiguous. It doesn't explicitly distinguish itself from the sibling update_project, which could also touch project metadata, so it stops short of a 5.

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

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

Usage is only implied by the mechanics of the sentence; there is no statement of when to prefer this over update_project or a reorder tool, and no prerequisites (e.g. folder must exist, project must belong to the caller).

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 non-destructive, idempotent mutation in a closed world. The description adds that the chosen core phrases are carried into every locale, which is useful behavioral context, but it does not explain what happens to any prior selection or what the response looks like.

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

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

Two short sentences with zero filler, and the main action is front-loaded. The sequencing note is compact and useful.

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 adequate for a simple three-parameter mutation, especially since the schema fully documents inputs. It still omits what happens after selection, such as any state change or what is returned, which would help an agent understand the full effect of calling it.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description reinforces the meaning of optionId and corePhrases but adds no syntax, formatting, or constraint details 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 states a specific action: picking a listing option and its core phrases for shipping into every locale. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like optimizer_save_option or optimizer_more_options.

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

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

It gives a clear next step (optimizer_localize), which implies this is part of a sequence. However, it does not say when to choose this tool over alternatives or what preconditions must be met before calling it.

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=false, destructive=false, idempotent=true, openWorld=false, so the safety profile is covered. The description adds the partial-update semantics (empty string clears a field), which is useful mutation context, but says nothing about whether edits touch only the draft or live listing, whether a publish action follows, or whether field choice depends on platform (Apple vs Google).

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 front-loaded sentence, no filler, and the most surprising behavior (empty string clears) is placed immediately after the scope statement.

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?

A nested-object mutation tool with three required params and no output schema; annotations cover safety and the schema covers field constraints in detail. What remains missing is the relationship to the draft/publish lifecycle and why the sibling tools differ, leaving the description only minimally adequate for a write operation with a nested payload.

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 every field carries its own platform-specific length guidance, so the schema does the heavy lifting. The description repeats the empty-string-clears rule already documented on the 'fields' property and adds no new meaning about 'locale' or 'projectId' 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?

Specific verb+resource: changes fields on one locale's draft listing, with the scope ('one locale's draft') made explicit and the clear-field convention stated. It does not name or contrast with the closest siblings (optimizer_localize, optimizer_save_option, optimizer_choose, publish_listing), so the agent must infer the boundary.

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

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

No statement of when to use this versus optimizer_localize (which presumably generates content) or optimizer_save_option / publish_listing. The only usage signal is implicit in the word 'draft'. Nothing tells the agent whether a separate publish step is required or which sibling to pick for a different edit.

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?

Adds real behavior beyond the annotations: it is a background (async) job, translation plus market measurement is performed, and one failed locale does not abort the rest, with failedLocales/lastError exposed via get_optimizer. This is meaningful context for a non-read-only, non-idempotent, open-world operation. It stops short of saying whether existing drafts are overwritten or how to poll for completion.

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, purpose first, failure semantics second, async nature last. Dense in the good sense, with only minor redundancy in describing the candidate-measurement pipeline rather than just the effect.

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

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

For a 5-parameter background mutation with no output schema, the description covers the effect, partial-failure behavior, and where to check status. It could add the completion/polling path (wait_for_jobs) and whether re-running replaces drafts, but nothing critical to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so scope, locales, remaining and directions are already well documented in the schema. The description echoes the locale/test-market concept but adds no syntax or defaulting detail for scope, locales, or remaining beyond what the schema states. 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?

"Write per-locale drafts of the chosen listing" gives a specific verb and resource, and the follow-on sentence explains what the write actually does (translate, measure candidates in the locale's test market, keep the best). It reads clearly as a distinct step from siblings like optimizer_choose or optimizer_edit_locale, though it never names those alternatives to draw the boundary explicitly.

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

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

"The chosen listing" implies this runs after a listing has been selected, and the reference to get_optimizer's failedLocales gives an implicit recovery path. But there is no explicit when-to-use/when-not-to-use guidance, no pointer that this is a background job requiring wait_for_jobs, and no statement of the prerequisite choice step.

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, openWorldHint=true and idempotentHint=false, so the agent knows this is a non-repeatable external generation. The description only adds that results sit 'next to the existing ones', which hints at append-vs-replace behavior, but says nothing about AI cost/latency, whether results persist, or whether save/choose calls are required afterward.

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

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

A single short sentence with no filler and the key notion (additional, alongside existing) front-loaded. It is efficient, though the brevity reflects under-specification rather than tight writing.

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?

This is a non-idempotent generative tool with no output schema, and the description never says what comes back (option objects? identifiers?), where they land, or that a follow-up optimizer_save_option/optimizer_choose is expected. Given the dense optimizer_* family and the openWorld annotation, this leaves too much for the agent to guess.

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% — count, projectId and directions are all documented in the schema, including the example creative direction. The description adds no meaning beyond that, 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?

It states a verb and an object (generate additional listing options), but 'options' and 'listing' are domain jargon not defined anywhere, and with ten other optimizer_* siblings the description gives no clue how this differs from optimizer_start or optimizer_pick_phrase. The purpose is inferable but not sharply distinguishable.

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

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

There is no statement of when to use this versus optimizer_start (initial generation) or optimizer_save_option (persisting a result), nor any prerequisites. The phrase 'next to the existing ones' weakly implies it is a follow-up call, but nothing is explicit.

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

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

Annotations already declare this as a non-destructive, idempotent write, so the safety profile is covered. The description adds the useful constraint that the phrase must be one of the locale's measured candidates from get_optimizer, but it does not explain what happens to the prior phrasing, whether the draft must be in a particular state, or what the response contains.

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

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

A single front-loaded sentence with no filler, though the nested phrasing ('different measured candidate phrase for a core phrase (from that locale's candidates...)') is slightly convoluted. It earns its place and avoids bloat.

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 in the optimizer workflow with no output schema, the description covers the core action and candidate source, and annotations cover safety. It remains thin on state prerequisites and post-call effects, leaving the agent to infer how this fits with optimizer_choose, optimizer_save_option, and optimizer_localize.

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 all four parameters (locale, keyword, phrase, projectId) are already documented, including the phrase being a candidate and the keyword being the main-locale core phrase. The description's reference to get_optimizer candidates adds slight linkage but no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb ('use a different...candidate phrase') and resource, scoped to one locale draft, and points to get_optimizer as the source of candidates. It does not explicitly distinguish itself from close siblings like optimizer_choose or optimizer_save_option, which keeps it from a 5.

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

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

The phrase 'In one locale draft' implies when this applies and the parenthetical indicates the phrase must come from that locale's candidates in get_optimizer. There are no explicit exclusions, prerequisites, or named alternatives, so guidance is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds one useful qualifier — that both generated and custom options can be removed, and only one at a time — but says nothing about permanence, undo, or side effects on dependent state.

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

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

A single short sentence with the destructive action front-loaded and zero filler. It is terse to the point of omitting any contextual sentence, but nothing written is wasted.

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

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

For a two-parameter, fully documented deletion with rich annotations and no output schema, most of what an agent needs is present. The remaining gap — whether deletion is reversible and what happens to state referencing the option — is material for a destructive tool and is left uncovered.

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 both parameters are documented in the schema, including the pointer 'from get_overview' for projectId. The description adds no format, sourcing, or validation detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete one listing option') and narrows the object to '(generated or custom) from the optimizer', which distinguishes it from broader tools like optimizer_reset. It does not explicitly name a sibling it could be confused with, so it stops short of a 5.

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

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

The description gives no when-to-use guidance and no alternatives — an agent must infer from the name whether this is the right tool versus optimizer_reset (clear all) or optimizer_save_option. Nothing about preconditions or consequences of use is 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 flag destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description earns credit by enumerating exactly what is destroyed (options, the choice, every locale draft), which the annotations do not. It stops short of saying the action is irreversible or that no confirmation is required.

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

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

One sentence that front-loads the destructive verb and immediately qualifies scope with "all". No filler and nothing the agent must scan past.

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 destructive tool, annotations plus the enumerated list of discarded artifacts give an agent nearly everything needed. Missing only an explicit irreversibility/confirmation note given destructiveHint=true.

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

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

Schema description coverage is 100% and the single parameter is documented in-schema, including a pointer to get_overview for obtaining the id. The description adds nothing about the parameter, 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?

A specific verb ("Discard") plus an enumerated resource set (all options, the choice, every locale draft) tied to a project. The word "all" implicitly separates it from the sibling optimizer_remove_option / optimizer_edit_locale tools, but no sibling is named explicitly.

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

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

There is no statement of when to reset versus when to use optimizer_remove_option, optimizer_choose, or optimizer_edit_locale to correct a single item. Usage is only inferable from the word "all"; no prerequisites, no confirmation guidance, no 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 non-read-only, non-destructive, non-idempotent, closed-world. The description adds real value beyond that: the app re-scores the saved option and surfaces validation problems (length limits, repeated words) in get_optimizer, which tells the agent the write has a follow-up verification path. It stops short of saying whether unspecified fields are cleared on replace.

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

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

Two tight sentences, the mode-switching rule is front-loaded, and the follow-up location (get_optimizer) closes the loop. Nothing is padded.

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

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

With no output schema, the description correctly points the agent to get_optimizer for the re-scoring and validation results, which is the key post-call behavior. Minor gaps remain around replace semantics (partial vs full overwrite) for a nested-object mutation.

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

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

Schema coverage is 75% and each nested listing field already carries its platform-specific length limits in the schema, so the schema does most of the work. The description restates the optionId omission rule that the schema description already states, adding no new syntax or format detail.

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 pair (add / replace) on a specific resource (a listing option) and ties the mode to optionId presence. It does not explicitly differentiate itself from nearby siblings like optimizer_edit_locale or optimizer_more_options, so it stops short of a 5.

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

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

The add-vs-replace decision is spelled out via the optionId conditional, which is genuinely useful routing. But there is no guidance on when to use this instead of optimizer_edit_locale, optimizer_more_options, or optimizer_choose, so tool-level selection is left to inference.

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

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

Goes well past the annotations (which only cover readOnly=false, idempotent=true, destructive=false) by disclosing merge semantics ('Omitted fields stay; empty strings clear'), the URL format constraint, and the language-scope behavior of allLanguages. These are non-obvious mutation traits an agent cannot infer from structured 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?

Dense and front-loaded with the resource and staging scope first, then platform specifics, then the caveats. The opening sentence is slightly awkward ('the listing links written by the next publish') but every sentence carries actionable information.

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

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

For an 8-parameter mutation with no output schema, it covers the essentials: staging, merge/clear semantics, cross-platform field mapping, and the URL constraint. It does not describe validation failures or whether a preview is returned, but the return-value burden is lighter here and the calling guidance is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps fields to platforms (Apple: whatsNew/marketingUrl/supportUrl/privacyUrl; Google: marketingUrl as contact website plus contactEmail) and defines the empty-string-clear and https:// rules. Only minor gaps remain, such as what happens when a field is omitted for one platform only.

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?

Starts with a specific verb+resource ('Set What's New and the listing links') and immediately scopes it as staged for the next publish, which separates it from the sibling publish_listing that actually writes them. An agent can tell what is modified and when it takes effect.

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

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

Explicitly states the precondition 'publish must be true for publish_listing to write them', which is the key routing rule against the write sibling. It stops short of a full when/when-not comparison, but the dependency on publish_listing is unambiguous.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false; the description adds genuinely new context beyond them by disclosing the replacement of prior options and that execution is asynchronous (background job), which materially changes calling behaviour. It stops short of covering runtime expectations, whether an AI provider must be configured first, or failure modes. Minor tension: 'replaces previous options' reads slightly destructive against destructiveHint=false, though the non-idempotent hint is consistent with regeneration.

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

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

Two sentences, front-loaded with the action and its output, followed by the side effect and the next step. Every clause (scouting, artifact list, scoring, replacement, async, follow-up read) carries information an agent needs; nothing is padding.

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

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

For a non-read-only, open-world background job with no output schema, the description covers what is generated, what gets replaced and where to look for results (get_optimizer). It does not mention whether to use wait_for_jobs to await completion or whether an AI provider must be set via set_ai_provider first, which are the remaining gaps for an async tool in this toolset.

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 projectId, locale, ai and directions are already documented in structured data, which sets the baseline at 3. The description reinforces that the locale is the 'main listing locale' and that keywords come from the project's board, but adds no format, default or constraint detail for the optional directions or ai provider parameters.

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

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

States a specific verb (start) and resource (listing optimizer) for a named scope (a project), then enumerates exactly what is produced: AI-written listing options with title, subtitle, keyword field and description, scored for reach and difficulty. The phrase 'scouts the board's keywords in the main locale' further pins down the input side, so an agent can tell this apart from optimizer_more_options or optimizer_choose without opening the schema.

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

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

Gives clear operating context: it is a background job and the follow-up step is explicitly 'then read get_optimizer', which routes the agent correctly after invocation. 'Replaces previous options' implicitly warns against calling it when existing options must be preserved, but it never names optimizer_more_options as the non-destructive alternative for adding options, so the sibling comparison is left to inference.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains the autocomplete querying method, merge order, meaning of position 1, what tracked marks, and that Google Play has no public source. Annotations already cover read-only and idempotent safety, and the description does not contradict them.

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 definition is front-loaded and largely waste-free, packing purpose, method, ordering, tracking, and limitations into a compact block. It is slightly dense and clause-heavy, but not bloated.

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

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

With no output schema, the description does the necessary work by explaining what is returned, how suggestions are ordered, and what tracked means. It also covers the main limitation, making it complete enough for an agent to invoke the tool 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%, so the baseline is 3. The description adds useful parameter-level meaning by stating that Google Play is unsupported and by clarifying that tracked relates to phrases already in the project, which helps interpret the store and projectId parameters.

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

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

The description clearly states the resource and scope: popular searches from a store's own autocomplete around a seed word in one market. It does not explicitly distinguish this from nearby siblings such as suggest_keywords or search_store, though it names add_keywords as the downstream action.

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

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

It gives a clear use case (finding high-demand phrases to add with add_keywords) and an important limitation (Google Play is unsupported). It does not compare against alternative tools or state when not to use this tool beyond the Google Play exclusion.

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?

Goes well beyond the annotations: it discloses the in-app confirmation dialog, what the owner sees there (store, app, version, locales, fields), the ~2 minute timeout, the resulting not_approved error code, and that publishing happens as a background job. These are non-obvious behaviors an agent could not infer from destructiveHint/openWorldHint 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?

Front-loaded with the "DESTRUCTIVE / LIVE" label, then preconditions, then mechanics, then next step. Despite its length, every sentence carries operational weight for a high-risk irreversible tool.

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

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

No output schema exists, yet the description covers the async job model, the failure code, and the follow-up tool to call. Nothing critical is missing for an agent to safely invoke and then verify this destructive operation.

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 projectId, ownerApproved, approval, and versionString are all documented in the schema. The description reinforces the approval intent but adds no new syntax or format meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

"DESTRUCTIVE / LIVE: pushes the chosen listing and every ready locale draft to App Store Connect or Google Play Console" names the exact verb, resource, and target systems. It clearly distinguishes this from read-only siblings like get_publish_preview by stating that it changes what real users see.

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

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

Explicitly states the when ('only call after the owner has reviewed the exact listing text and explicitly told you to publish in this conversation') and the when-not ('never on your own initiative and never as part of a larger plan they approved in general terms'). It also names the prerequisite (connected console) and the required follow-up (wait_for_jobs).

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds important non-obvious behavior: projects inside the folder are preserved and moved to the top level, which is valuable 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?

Two short sentences, front-loaded with the action and followed by the key side effect. Every sentence earns its place with no wasted text.

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 delete tool with annotations covering safety and a fully documented schema, the description provides the essential behavioral detail about project preservation. 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%, and the single folderId parameter is documented in the schema. The description does not add further meaning about the parameter, 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 states a specific verb and resource: "Delete a folder." It is immediately distinguishable from siblings like save_folder and remove_project, and the added sentence clarifies the scope of deletion.

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 by naming the delete-folder action, but it does not explicitly state when to use it versus alternatives or any prerequisites. For a simple destructive operation, this is minimally adequate but lacks explicit routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered by structured data; the description earns credit for adding that rank history is destroyed along with the keyword, which is not derivable from annotations or schema. It does not discuss failure behavior for unknown ids or whether deletion is bulk-atomic.

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

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

Two short sentences, front-loaded with the destructive consequence before the alternative guidance. No filler, though the second sentence's mixed phrasing keeps it just short of ideal.

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 destructive tool with full schema coverage and destructive/idempotent hints, this covers purpose, blast radius, and routing to the safer sibling. Only the bulk limit and behavior on invalid ids are left entirely to the schema.

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

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

Schema coverage is 100% and the single parameter already documents its source (get_project_board), the 1-100 array bounds, and id length limits. The description adds nothing parameter-specific, 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?

"Permanently delete keywords and their rank history" names a specific verb (delete), resource (keywords), and secondary consequence (rank history loss), which distinguishes it from the mutation siblings like edit_keyword and add_keywords.

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

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

Explicitly names the preferred alternative and the exact condition that selects it: use edit_keyword hidden:true unless the owner wants them gone. This is a when/when-not statement with a named sibling.

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 flag destructive=true and idempotent=true, but the description adds what an annotation cannot: the exact cascade (keywords, rank history, optimizer drafts), the irreversibility ("Permanently"), and the fail-safe that a confirmName mismatch deletes nothing. That is real behavioral context beyond structured 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, zero filler. What is destroyed comes first, then the precondition and the safety guarantee, in the order an agent needs them before committing to a destructive call.

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 destructive tool with strong annotations, all the decision-relevant facts are present; even the no-output-schema gap is minor since a delete's outcome is binary. It stops short of describing the success response (deleted counts / confirmation payload) or error modes for a nonexistent projectId.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the consequence of confirmName (mismatch = no deletion) and ties the value source to get_overview, which the schema only states in shorthand. It does not add anything for projectId 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?

States a specific verb and resource ("Permanently delete a project") and immediately scopes the blast radius to keywords, rank history and optimizer drafts, which no sibling delete/move tool does. An agent can distinguish this from remove_keywords, remove_folder, move_project or update_project 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?

Gives an explicit gating condition — "Only when the owner asked for this exact project" — plus the required confirmation flow, so the agent knows when to proceed and when to abort. It does not name alternative tools for narrower intents (e.g. removing only keywords), which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the source is the external store and that console data is only included when connected, which is useful context. It does not disclose whether re-importing overwrites local edits to the listing metadata, which is the primary risk for a non-idempotent re-import — a notable omission given the mutation flag.

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

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

One short sentence with the operation front-loaded and no filler. The parenthetical qualifier is compact rather than padded, so nothing needs cutting, though the phrasing 'live listing / metadata' is slightly loose.

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, no-output-schema refresh tool whose annotations carry the safety profile, the definition covers what it does, where it pulls from, and the console precondition. The remaining gap is the absence of any statement about what happens to existing local metadata or what the caller should do afterward.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains projectId and even points at get_overview as the source. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Re-import') on a specific resource ('live listing / metadata from the store'), which is clearer than the title's generic 'Refresh app metadata'. It implicitly distinguishes itself from update_project by stressing it pulls from the store rather than editing project fields, though it never 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?

Usage is only implied: the agent can infer this is the tool to pull freshest store data into the project, and the parenthetical '(and console when connected)' suggests a precondition. But there is no explicit when-to-use guidance, no mention of when NOT to use it, and no reference to alternatives such as update_project, connect_console, or import_file.

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?

Adds real behavioral context beyond the annotations: it runs as a background job, the store is rate-limited so large boards take minutes, and results from today are reused unless force is true. That caching semantic is not expressible in the annotations. The gap is that it never says how to obtain or poll the job's results (wait_for_jobs, get_project_board), which matters for an async tool.

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

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

Three sentences, zero filler, with the core action first and the operational caveats (background job, rate limit, reuse rule) after. Each sentence carries distinct information.

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

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

Wait — reassessing: for a mutation-ish async job with full schema coverage and no output schema, the description should say how results surface. It does not mention result retrieval or how to wait, which is a meaningful omission for a background job tool. Score adjusted to 3.

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

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

Schema coverage is 100%, so the schema already documents projectId, markets and force. The description reinforces the force=true behavior (overriding same-day reuse), adding slight nuance, but contributes nothing about markets or projectId 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?

States a specific verb and resource: searches the store for the project's keywords and records rank, volume/difficulty and competitor data. This is clearly distinguishable from read-only siblings like get_term_detail or fetch_popularity, and the scope (every keyword in the project's markets) is 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?

The description implies when to use it (populating rank data for a project) and covers the reuse-vs-force condition, but never names alternatives or exclusions — an agent cannot tell from this text whether to use run_rank_check, fetch_popularity, or get_project_board for a given need. 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 establish that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds the dual create/rename mode, but does not cover side effects, failure conditions, or return 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?

It is a single, front-loaded sentence with no wasted words. The create-versus-rename distinction is 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 simple two-parameter mutation with full schema coverage and useful annotations, the description is complete enough to call correctly. Minor ambiguity remains around results and sibling selection, but no output schema exists to require return-value documentation.

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 both parameters are documented there. The description restates the folderId omission rule for creation but adds no syntax, validation, or edge-case 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 specific verbs and resource: 'Create a folder' or 'rename an existing one.' It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as remove_folder.

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

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

It gives a useful in-tool rule: omit folderId to create, provide it to rename. However, it does not compare against alternatives like remove_folder or explain when this tool should be chosen over other folder/project operations.

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?

Adds real context beyond the annotations: this is an asynchronous background job, and rendering/upload happen in the app rather than in the tool. It also hints at state change without contradicting destructiveHint=false. Missing only cost/rate or failure-mode details.

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 the action and the scope, then the prerequisite and follow-up. Slightly telegraphic phrasing ('Every slide needs a main heading first') keeps it from a 5, but nearly every sentence carries information.

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

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

For a fire-and-forget background mutation with no output schema, it supplies the missing pieces: it is async, the visible result appears via get_screenshots, and rendering/upload are handled elsewhere. That is enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description only reinforces the `locales` filter and says nothing about `ai` or `projectId`, so it adds little 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?

States a specific verb and resource: adapting main screenshot headings into the project's other languages, optionally limited to `locales`. It is distinguishable from screenshots_write_headings via the 'Every slide needs a main heading first' prerequisite, though it never names that 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?

Gives a clear precondition (headings must already exist on every slide) and tells the agent what to do afterwards (read get_screenshots to see translated/stale/missing per locale). It lacks explicit when-not-to-use guidance or named alternatives, 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 only declare the mutation/async profile; the description adds the important behaviors — AI-generated content, non-destructive preservation of existing headings, and that this is a background job requiring a subsequent get_screenshots read. It also documents generation constraints (verb first, one benefit, 34/40 chars). Provider cost/rate limits and failure handling are not covered.

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

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

Three tight sentences, front-loaded with the core action and constraint, then the overwrite rule, then the async/follow-up note. The parenthetical constraint block is dense but every clause carries actionable information.

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

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

For a non-idempotent, open-world generation tool with no output schema, the description covers what it produces, what it preserves, how it runs (background) and how to retrieve results. It omits provider/permission prerequisites implied by the ai and projectId params.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics: the interplay between overwrite and slideId ('unless overwrite is true or slideId names one slide') and the output constraint of the main locale and character limits that shape what the ai/directions params produce.

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

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

States a specific verb+resource: the AI writes the one-line heading printed on each screenshot slide. It is clearly distinct from siblings like get_screenshots (read) and screenshots_translate (localization), and it even names get_screenshots as the follow-up read step.

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 concrete conditions: existing headings are kept unless overwrite is true or slideId targets a single slide, and it states the prerequisite ('Slides and images are set up in the app') plus the next step ('then read get_screenshots'). It does not explicitly route the agent away from near alternatives, 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.