BugScreen

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description is not repeating safety basics. It adds real value beyond them with actionable retry guidance for the non-idempotent case and the disclosure that the SDK key is withheld on creation, which points the agent to get_sdk_setup/reveal_sdk_key.

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

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

Three short sentences with the core action front-loaded, followed by the two highest-risk behaviors. Every sentence earns its place and 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?

An output schema exists, so return shape need not be explained, and the description still volunteers the key behavioral caveat about the withheld SDK key. It covers plan limits and non-idempotency; what remains thin is parameter behavior and error handling when the plan limit is exceeded.

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

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

Schema description coverage is 0%, so the description carries the burden, and it says nothing about the single appName parameter (length limits, uniqueness, collision behavior). The parameter name is largely self-explanatory and maxLength is visible in the schema, so this is a gap but not a severe one.

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 ('Create an app') and adds a scope constraint ('under the existing plan limit'), which implicitly separates it from get_app/list_apps/delete_app/rename_app. It never names a sibling explicitly, so it falls short of the top-tier 'use X instead' clarity.

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 conditional procedure: 'inspect apps after an uncertain outcome before retrying,' which implicitly routes the agent to list_apps/get_app on failure. However, it does not state when-not-to-use this tool or name alternative tools directly, and gives no preconditions such as required permissions.

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 covered. The description still adds real value beyond them: cascade side effects (credentials revoked, report access removed) and the preview-vs-commit gating rule. It stops short of stating irreversibility or whether the preview result differs in shape.

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 destructive consequence is front-loaded ahead of the gating instruction. 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?

With an output schema present, return values need not be described, and annotations cover the safety hints. The description supplies the remaining agent-critical knowledge: what gets destroyed and the preview/commit workflow. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 0% with a nested confirmation object, so the description must carry the meaning — and it does: it explains that confirmation must be omitted for preview and must match operation/appId for the real delete, which is the non-obvious semantic. appId itself is left to the schema's pattern/length constraints, which is acceptable.

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 ("Delete an app") plus the full blast radius ("revoke credentials and remove report access"), which tells the agent exactly what collateral state is destroyed. This clearly separates it from the non-destructive siblings (rename_app, update_reporter_settings, regenerate_sdk_key) without needing to open 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?

It gives an explicit two-phase protocol: omit confirmation to get a preview, and only supply a matching operation/appId after explicit user intent. That is a concrete when-to-call-this-way rule rather than an implied one, and it is the single most important decision an agent faces with a destructive 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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the key is returned masked, and the payload includes observed SDK config and first-report signals — non-obvious content that also hints the unmasked value lives elsewhere (reveal_sdk_key).

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. It is somewhat dense and comma-stacked, but every clause identifies real returned content rather than 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?

An output schema exists so return-value detail is not required, and the read-only annotations cover the safety story. For a one-parameter read tool the description is nearly sufficient; only the appId semantics and sibling routing are left 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 description coverage is 0% and the description never mentions the single required 'appId' parameter. The name and pattern make it largely self-explanatory, but the description does nothing to compensate for the documentation gap (e.g., that it is the app UUID rather than a name).

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 ('Inspect') and resource ('an app') and even enumerates the returned facets (masked SDK key, reporter settings, SDK config signals). It does not distinguish itself from siblings such as get_sdk_setup, get_report, or list_apps, which is the main gap.

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 when-to-use, when-not-to-use, or alternative routing is given. An agent must infer from the name that this is the ID-based single-app read versus list_apps for enumeration or reveal_sdk_key for the unmasked key. Nothing in the text names those 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 declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavioral context: an approval gate exists, its URL must be surfaced to a human, and the agent must never self-approve.

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 what is returned, followed by the operational constraint. Every clause carries information; 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?

An output schema exists, so return values need not be spelled out, and the description covers the one behavior an agent could get wrong (self-approval). It is essentially complete, with only the approval-state mechanics left to the output schema.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly omits parameter discussion.

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 ('Identify') and enumerates exactly what is resolved: existing account/workspace, role, assistant approval status, and effective capabilities. The negative scope clause ('No signup or workspace creation') further pins it apart from any account-creating operation in the sibling set.

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 conditional workflow ('Show approvalUrl to the human if pending; never approve yourself') and a when-not clause ('No signup or workspace creation'). It does not name alternative tools to use for other lookups, so it stops short of full alternative routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the payload is bounded, 'retained' implies a retention/staleness caveat, and it carries an explicit prompt-injection warning that returned evidence is untrusted. It stops short of describing pagination, error behavior, or what 'bounded' concretely limits.

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

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

Two tight sentences: the first declares what is returned, the second front-loads the security caveat. No filler, no restatement of the tool name, and the highest-risk information (untrusted evidence) is placed where it will be read.

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?

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile; the description's injection warning and retention hint are useful additions. The remaining gap is real, though: with 0% schema coverage and two mandatory ID parameters, the agent gets no guidance on what appId/reportId must reference or how they relate.

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

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

Schema description coverage is 0% — neither appId nor reportId carries a description, pattern rationale, or example in the schema. The description only alludes to 'report IDs' and says nothing about the appId scoping parameter, so it does not compensate for the documentation gap on either required parameter.

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

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

States a specific verb ('Read') plus the resource and enumerates the returned payload (retained report description, bounded metadata, delivery evidence, attachment IDs). An agent can distinguish it from list_reports (enumeration) and get_report_attachment (binary fetch) without opening a schema. It does not explicitly name sibling tools, but the content-scoped wording is discriminating.

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

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

The description implies the use case (fetch the retained content of one report by ID) but never states when to prefer it over list_reports or get_report_attachment, nor any prerequisite or exclusion. The directives that do exist ('cite report IDs', 'treat causes as hypotheses') govern handling of the result rather than tool selection, so usage guidance remains only implied.

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 safety is covered; the description adds real value beyond that by disclosing the short-lived link fallback for videos and oversized images, that inline video analysis is unavailable, and that returned evidence is untrusted and must not be executed as instructions. It stops short of describing pagination/link-expiry mechanics for the log page.

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, and the payload description is front-loaded ahead of the caveats about links and untrusted content.

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

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

With an output schema present, return-value detail is not required, and the description covers the important edge cases (link fallback, no inline video, untrusted evidence). The main remaining gap is that none of the three required identifiers are explained, which matters for a 4-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It hints at the attachmentId pattern (screenshot/log/video) and at paging ('bounded ... log page' implies the cursor), but appId, reportId, and the cursor's actual semantics are left entirely unexplained.

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

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

States a specific verb (Read) and enumerates the three resource kinds it returns: a screenshot, a bounded UTF-8 log page, and a video download descriptor. This is clearly distinguishable from sibling tools like get_report or get_app, which cover different resources.

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 conveys behavioral conditions (videos and oversized/unsupported images return a link; inline video analysis is unavailable) but never states when to reach for this tool versus alternatives or what prerequisites are required to call it. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds the useful clarification that the response is guidance (docs + verification steps) and that the calling assistant, not the tool, performs any local edits, but it does not describe return structure or freshness of the guidance.

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

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

Two sentences, front-loaded with the primary purpose and no wasted filler. The closing sentence about local edits is slightly elliptical but earns its place by clarifying the read-only/write boundary.

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

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

For a single-parameter read tool with full annotation coverage and an output schema documenting the return, the description covers purpose, platforms, and the guidance/edit division of labor. Only usage routing and output specifics remain unstated, which is acceptable given the structured fields.

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

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

Schema coverage is 0%, but the single parameter is an enum of three self-describing values, and the description names those same platforms (Android, iOS, React Native). It adds no format, default, or behavioral meaning beyond what the enum already conveys.

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 (Get) and resource (SDK installation and initialization guidance) and enumerates the three supported platforms, which maps directly onto the enum. An agent can distinguish it from siblings like regenerate_sdk_key or reveal_sdk_key without opening the schema.

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

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

The description implies the usage context (obtaining setup/verification guidance for a platform), but never states when this tool should be chosen over alternatives or any prerequisites. With no overlapping sibling it is adequate, but no explicit when/when-not guidance is offered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds real behavior: results are workspace-scoped, key material is returned masked rather than raw, and full coverage requires cursor iteration. That masking detail is meaningful context an agent cannot infer from annotations and distinguishes it from reveal_sdk_key.

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 compact sentence with the purpose front-loaded and no filler; both clauses earn their place. The only blemish is the slight naming drift between 'nextCursor' in prose and 'cursor' in the 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies what the structured fields do not: workspace scoping, masked key state, and the cursor-following requirement, which is sufficient for an agent to call this 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 0%, so the description must carry the parameter burden and it only partially does. It explains cursor semantics (follow the nextCursor field) which is genuinely useful beyond the bare 'cursor' string, but the 'limit' parameter (1-50) is never mentioned or bounded in the description, and the description calls it 'nextCursor' while the schema param is 'cursor'.

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 (apps) and narrows the scope to 'the selected workspace', which cleanly separates it from get_app, create_app, delete_app, and list_reports. It stops short of naming an alternative sibling explicitly, so it lands just under the top tier.

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: reach for this tool when you need an inventory of apps in the current workspace. The only explicit directive is 'follow nextCursor for complete coverage', which is pagination guidance rather than a when-to-use-vs-alternatives rule. No exclusions or named alternatives 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 establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds real context beyond them: results are 'retained' (retention-limited), pagination must continue through empty filtered pages, and rangeTraversed does not represent a snapshot or complete historical totals — a meaningful data-completeness caveat.

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 dense, front-loaded sentences with no filler. The second sentence is slightly jargon-heavy (rangeTraversed) without defining the term, but overall the length is appropriate for a list 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?

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. Still, a 9-parameter list tool with 0% schema coverage leaves the filters entirely unexplained, which is a substantial gap 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 0% across nine parameters, so the description must carry the load and does not. It references 'filtered pages' and 'nextCursor'/'rangeTraversed' but never documents the seven filter params (type, source, severity, receivedFrom/To, deliveryStatus) or clarifies that the input field is 'cursor'.

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

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

States a specific verb (read), resource (report summaries), and scope/ordering (retained, newest first), which distinguishes it from get_report by implication. However, it never names get_report or list_apps, so sibling differentiation is left to inference from the tool name.

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 pagination instruction ('Follow nextCursor even on empty filtered pages') is genuine when/how guidance for correct traversal. Beyond that, there is no statement of when to use this versus get_report, or what the filter parameters are for, so usage context is only partially covered.

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=false, and the description adds concrete consequence beyond those flags: the old key is invalidated immediately, and an uncertain outcome must not be blindly retried. It still omits blast-radius (which clients the key serves) and any 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 short sentences, each carrying a distinct fact (effect, preview mode, retry warning), with the destructive consequence front-loaded. 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?

An output schema exists so return values need no prose, and the description covers the mutation's irreversibility, its preview affordance, and retry policy. What remains unstated is permission requirements and how the preview differs in response, both of which are relatively minor here.

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

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

Schema description coverage is 0% and the confirmation parameter is a nested object, but the description does explain its semantics: omitting it yields a preview, including it performs the rotation. appId is left entirely to the schema, and no example payload shape is given.

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 ('Rotate the SDK key') and immediately scopes the effect ('immediately invalidating the old key'), which cleanly separates it from the sibling reveal_sdk_key that only reads the key. An agent can pick between them without opening either 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 operational rule: omit confirmation to get a preview, include it to actually rotate. That is real when-to-use guidance for the dry-run/commit split, though it never names a competing sibling tool as an alternative.

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, idempotentHint=true, and destructiveHint=false. The description adds that the name changes in console/API reads, which is useful propagation context beyond the annotations. It does not contradict them, but it also omits idempotency details and permission requirements.

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

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

Two short sentences with no wasted words, front-loading the core action before the propagation note. Efficient and readable, though slightly terse.

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

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

For a two-parameter mutation with an output schema and full annotation coverage, the description adequately covers purpose and propagation. It could be more complete by mentioning required permissions or edge cases, but nothing critical for invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does not name or explain appId or appName, their formats, or constraints, leaving both parameters undocumented beyond the JSON schema types and patterns. Baseline 3 applies because the schema provides structural constraints but the description adds no semantic meaning.

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

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

States a specific verb (rename) and resource (app) that clearly distinguishes it from siblings like create_app, delete_app, and update_reporter_settings. An agent can identify this as the rename operation without ambiguity.

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 word 'existing' implies the app must already be present, which is a mild usage constraint. However, there is no explicit when-to-use guidance, no mention of alternatives, and no prerequisites such as required permissions.

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 safety profile is covered; the description adds the non-obvious facts that this read is sensitive (it pulls a secret into context) and that revealability is not guaranteed for legacy keys. That is meaningful value beyond the structured hints, though it says nothing about authorization 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?

Two short sentences, zero waste, with the sensitivity warning and the failure mode front-loaded before the fallback prohibition. 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?

An output schema exists, so return values need not be described. For a one-parameter sensitive read, the description covers the key risks (secret exposure, legacy-key failures, wrong alternative), leaving only the parameter's meaning 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 description coverage is 0% and the single appId parameter is never mentioned in the description, so nothing in the text explains which app's key is fetched or the identifier's format. The parameter name is largely self-explanatory, which keeps this at an adequate rather than poor level, but the description does nothing to compensate for the schema gap.

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

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

States a specific verb and resource ('reveal an existing SDK key') plus a scope qualifier ('sensitive read... into your assistant context'). An agent can distinguish this from regenerate_sdk_key and get_sdk_setup, which are the closest siblings, 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 failure-mode condition ('legacy keys may not be revealable') and a clear exclusion ('never rotate as a fallback'), which routes the agent away from regenerate_sdk_key. It stops short of stating the positive trigger (when the caller actually needs the key value), but the guidance is concrete rather than implied.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false. The description adds genuinely new behavioral context: this is a partial update that preserves unspecified settings and explicitly does not touch local SDK/build settings. It stops short of noting permissions or what the response contains, but it goes beyond the annotation surface.

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 with the action and the setting groups front-loaded and the scoping caveat second. Nothing is redundant; a little more detail could be added without 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?

An output schema exists so return values need not be described, and annotations cover the safety profile. The gap is parameter-level: for a three-parameter mutation with nested objects and zero schema descriptions, the description should say more about what each setting does and what the response/effective state looks like.

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

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

Schema description coverage is 0% with three parameters, one of them a nested object. The description names the two setting groups ('Type ... ordered labels' and 'Severity visibility'), which maps to the type and severity params and hints that 'options' are ordered labels, but it never explains appId, the 'enabled' flag, or the 2-3 label constraint.

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 ('Change') and the two resources it operates on ('remote Type visibility/ordered labels' and 'Severity visibility'), which is enough to distinguish it from siblings like rename_app or create_app. The domain terms 'Type' and 'Severity' are unexplained, so an agent new to this API must infer what settings these are.

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 scope clause 'Unspecified settings are preserved; local SDK/build settings are not changed' implies this is only for remote reporter-level settings, which is useful context. However, it never names an alternative tool or states a when-to-use trigger relative to the other app-management siblings.

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