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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful context: the API returns a string yes/no and the tool normalizes to {allowed: bool, ...}. The ellipsis hints at extra fields but doesn't say what. Reasonable value added atop 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 tight sentences, no waste. Front-loads the purpose then the return shape. Slightly under-specified rather than verbose, which is the right trade-off.

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, so the description should fully explain return values; it gives {allowed: bool, ...} which is partial. For a read-only permission check this is mostly adequate, but the vagueness of the extra return fields leaves a 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 coverage is 100% and both resource/action have enums, so the schema does the heavy lifting. The description mentions subresource and resource/action but adds no syntax details beyond the schema (e.g., what */* vs proj/app means is only in the schema description). 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 (check) and resource (whether account may perform resource/action on subresource). Clearly an RBAC permission-check tool, distinguishable from the siblings which mostly list/get actual resources. No explicit sibling differentiation, but the purpose is unambiguous.

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

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

No guidance on when to use this versus, say, argocd_get_userinfo or the actual resource tools. No exclusions, no mention of whether it reflects live RBAC, policy caching, or project-scoped permissions. An agent must infer usage entirely.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely non-redundant behavior: the result is returned as a slimmed application, and the operation is idempotent only when upsert=True. It does not discuss side effects on the destination cluster or auto-sync consequences, so it is strong but not exhaustive.

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

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

Three short sentences, no filler; the core action and its parameter model come first, then the alternative tool, then the return/idempotency note. Every sentence earns its place.

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

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

For a 22-parameter creation tool with 100% schema coverage and no output schema, the description covers the key non-schema facts: return shape, idempotency, and the fallback tool. Remaining gaps (auth/permission needs, whether creation triggers a sync) are minor given the annotation and schema coverage.

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% across all 22 parameters, so the schema already documents each field including upsert and its meaning. The description only restates the upsert idempotency relationship, adding no syntax, format, or dependency detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Create an application') and immediately scopes it ('from flattened parameters'), which tells the agent this is the declarative/patchy path rather than an apply. It routes away from the sibling argocd_patch_application for uncovered fields, so it is distinguishable without opening the schema, though the phrase 'flattened parameters' is slightly jargon-like.

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 an explicit alternative ('Use patch for anything this does not cover') and a conditional behavior ('Idempotent only with upsert=True'), which is real when-to-use guidance. It stops short of a full when/when-not boundary against siblings like argocd_generate_applicationset or argocd_sync_application, so it is clear context without exhaustive 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 destructiveHint=true and openWorldHint=true, so the 'destructive' label is redundant. The added 'cascade=False removes only the Application object' clarifies the scope of deletion, but permissions, irreversibility, and 404/403 behavior are left to the 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?

The definition is short and front-loaded, but the standalone 'destructive.' fragment duplicates the annotation and does not earn its place.

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

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

The schema documents all five parameters and annotations cover the safety profile, so the sparse description is minimally adequate. However, for a destructive multi-parameter tool, it omits prerequisites and alternative deletion paths that an agent might need.

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 baseline is 3. The description only touches the cascade parameter and adds no syntax or semantics beyond what the schema already 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?

States a specific verb and resource ('Delete an application'), which is enough to distinguish it from sibling deletion tools like argocd_delete_resource. The agent can identify the object type being deleted 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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternatives are named. The cascade note implies a choice but does not tell the agent when to choose cascade true versus false.

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 openWorldHint=true, and the trailing word 'destructive.' merely restates them. The description adds nothing about what is actually removed (the live object only, not the Git manifest), how force/orphan change the outcome, or any permission requirements.

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

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

A single front-loaded sentence with no wasted clauses. The trailing fragment 'destructive.' is redundant with the annotations and slightly dilutes the sentence, keeping it from a 5.

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?

Annotations fully cover the safety profile, the schema documents every parameter, and no output schema is present to explain. The description supplies the one thing structured fields cannot: that this is a transient delete whose purpose is controller-driven recreation.

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% across all 10 parameters, including nuanced entries for project, orphan, force, and app_namespace, so the schema carries the burden. The description contributes no parameter meaning beyond that 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?

States a specific verb+resource ('Delete a single managed resource') plus the consequence ('so the controller recreates it'), which separates it from argocd_delete_application and argocd_run_resource_action. It never names those siblings, so an agent must infer the distinction from the word 'managed resource'.

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 clause 'so the controller recreates it' implies the intent (forcing reconciliation/self-heal) and is the closest thing to usage guidance. There is no explicit when-to-use, no prerequisites, and no mention of argocd_delete_application as the alternative for removing the app itself.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered; the description reinforces this with 'Creates nothing' and adds a concrete input constraint ('The manifest must be JSON'). It stops short of describing how large a preview can be or any limits.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the two facts an agent most needs (no side effects, JSON input). 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 two-parameter, read-only dry-run tool with no output schema, the description conveys the action, the no-side-effect guarantee, and the input format. It could say a bit more about what the returned preview contains, but nothing essential is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description's 'manifest must be JSON' restates the applicationset parameter's own description and adds no new semantics for appset_namespace; 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 ('Dry-run the generators ... the applications an ApplicationSet would produce') and clearly distinguishes itself from read-only siblings such as argocd_get_applicationset and argocd_list_applicationsets, which return existing objects rather than previewing generated ones.

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?

'Dry-run' and 'preview' imply the use case (checking what an ApplicationSet would generate before applying it), but there is no explicit statement of when to prefer this over argocd_get_applicationset or of any prerequisites. Usage is inferable rather than spelled out.

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 openWorldHint, so the safety profile is covered. The description adds genuine behavioral context that annotations cannot: refresh=hard forces reconciliation and re-fetches target manifests from the repo server, i.e. it has side effects on cache/repo despite being a read. It does not describe error behavior (404/403), which the schema covers instead.

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, with the primary purpose and return shape front-loaded ahead of the refresh nuance. Every clause earns its place.

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

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

There is no output schema, so the description correctly enumerates the returned fields (spec, sync/health, conditions, operation, summary, resource counts). For a 6-parameter read tool in a cluster of 40+ siblings, that is sufficient, though it omits any hint of response size or cost of the full/refresh options.

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% with per-parameter descriptions and enum values, so the schema carries the load and baseline is 3. The description's refresh=hard note largely restates the schema's own wording ("hard re-fetches from the repo server"), adding only the word "reconciliation" beyond it.

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?

"Get one application" names a specific verb and resource, and the enumeration of returned facets (spec, sync/health, conditions, operation, summary, resource counts) distinguishes it from the sibling argocd_list_applications. An agent knows this is the singular, detailed read.

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 "one application" and the required name parameter, and the refresh=hard sentence hints at when to force a re-fetch. However, it never states when to prefer argocd_get_manifests, argocd_get_resource_tree, or argocd_get_application_history over this tool, nor any prerequisites.

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, openWorld), so the bar is lower. The description still adds real behavioral context beyond them: results are ordered newest first and event messages are truncated at 500 characters, which affects what the agent can expect to read.

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; the resource, ordering, and truncation constraint all appear immediately.

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 nine-parameter read tool with annotations covering safety and no output schema, the description is nearly sufficient. It omits mention of paging semantics (limit/offset interaction) and the warning-only filter, which is a minor gap given the schema documents them.

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

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

Schema description coverage is 100%, so all nine parameters (limit, offset, project, warnings_only, resource filters, app_namespace) are already documented in the schema. The description adds no parameter syntax or interaction detail, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Get Kubernetes events for an application') plus two distinguishing behaviors: newest-first ordering and 500-char message cap. It does not explicitly contrast with siblings like argocd_get_pod_logs or argocd_get_resource, but no other sibling serves events, so ambiguity is low.

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 purpose statement; there is no explicit when-to-use, when-not-to-use, or routing to an alternative (e.g. pod logs vs application events). The agent can infer intent but gets no decision 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 this as a safe, idempotent, read-only operation, so the safety profile is covered. The description usefully adds result ordering (newest first) and the returned fact set, but says nothing about paging behavior or volume despite limit/offset parameters.

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 that front-loads the operation and then lists the returned fields and ordering. Nothing is redundant, though it is arguably terse enough to leave gaps.

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

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

For a read-only paged history lookup with a fully documented schema and no output schema, the description covers what the tool returns and its ordering. The main omissions are guidance on paging and on choosing this over adjacent history/event tools.

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 five parameters (name, limit, offset, project, app_namespace) are already documented in the schema, including the 404/403 semantics for project. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource (get deployment history for an application) and even summarizes the payload: revision, who deployed, and the source, ordered newest first. It is clearly separable from siblings like argocd_get_application_events or argocd_get_revision_metadata, though it never explicitly names those alternatives.

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

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

There is no when-to-use guidance and no mention of alternatives. An agent must infer that this is for historical deployment inspection rather than current state, and nothing tells it whether to prefer this over argocd_get_application_events or argocd_get_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 declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful content context by naming the returned fields, but says nothing about the effect of the full/include_template/include_applications flags or namespace defaulting.

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 well-formed sentence that front-loads the action and resource and packs the return contents without waste.

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 partially compensates by summarizing the returned shape (generators, strategy, generated-app statuses), and annotations cover safety. It is adequate for a read-only getter, though it does not explain how the include flags alter 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 description coverage is 100% across all five parameters, so the schema fully documents name, namespace, full, include_template, and include_applications. The description adds no syntax or defaulting detail beyond that, 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 and resource ('Get one ApplicationSet') and enumerates what is returned (generators, strategy, generated-app status), which distinguishes it from the list and generate siblings. It does not explicitly name an alternative tool, 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?

'Get one' implies single-resource retrieval as opposed to argocd_list_applicationsets, but there is no explicit when-to-use/when-not guidance and no pointer to a sibling such as argocd_generate_applicationset. Usage is inferable but not stated.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the bar is lower, and the description adds a genuinely useful non-obvious behavior: the credential config is always stripped, even with full=True. That is a security-relevant disclosure the annotations do not provide. It omits any note on error behavior when the cluster is not found.

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 primary lookup behavior front-loaded and the credential caveat second. Nothing can be removed without losing 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?

For a read-only two-parameter get tool with no output schema and annotations already declaring the safety profile, the definition covers the essential call path and its most surprising side effect. A brief note on the returned shape or not-found behavior 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?

Schema coverage is 100%, so both parameters are already documented, and the baseline is 3. The description mildly reinforces the 'cluster' identifier semantics and clarifies that full=True does not restore credentials, but adds no syntax or format 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 (Get) and resource (one cluster) plus the lookup key (name or server URL), which clearly separates it from the sibling argocd_list_clusters that returns many. It does not name the sibling explicitly, 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 implied: 'Get one cluster by name or server URL' tells the agent this is the single-cluster lookup path, and the sibling naming list makes the alternative evident. But there is no explicit when-to-use/when-not statement or prerequisite guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description still adds real behavioral value: default truncation of diffs and the side effect that include_states injects parsed target/normalized-live/predicted-live manifests with managedFields stripped, which is not in 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 tight sentences with no filler; the core behavior (diff retrieval, truncated by default) is front-loaded before the include_states elaboration. Slightly dense/technical but every clause earns its place.

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

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

With 11 parameters, no output schema, and only 1 required parameter, the description covers the key output-shaping flags but says nothing about the overall return structure, the effect of the sibling filter parameters, or how results are paged/limited. Adequate given the 100% schema coverage and read-only annotations, but not complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully elaborates on include_states beyond the schema's terse 'Include parsed target/live/predicted states' by explaining the manifests added and that managedFields are stripped, and confirms the diff-truncation semantics behind max_diff_chars.

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

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

States a specific verb and resource ('Get managed resources') plus the salient output characteristic (live-vs-desired diffs, truncated by default). It is clear what the tool returns, though it never names or contrasts with overlapping siblings such as argocd_get_resource_tree, argocd_get_resource, or argocd_get_manifests.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternative tools for inspecting application resources. The only implicit context is that diffs are truncated by default and include_states expands output, which hints at usage but does not guide tool selection.

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 openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: results are parsed into discrete objects and are paged. It stops short of describing error behavior, though the schema's 'project' field hints at 404/403 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 front-loaded sentence with no filler; every clause ('rendered desired', 'for a revision', 'parsed into objects', 'paged') 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?

With no output schema, the description should carry more of the return-shape burden; 'parsed into objects' is helpful but the object structure and paging envelope remain unspecified. For an 8-parameter read tool this is adequate but not complete.

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

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

Schema description coverage is 100% across all 8 parameters, including non-obvious semantics for name (namespace/name form), project (404 vs 403), and app_namespace (ARGOCD_APP_NAMESPACE default). The description adds nothing parameter-level, 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 ('Get') and a precisely scoped resource ('rendered desired manifests for a revision'), plus the output shape ('parsed into objects and paged'). This implicitly distinguishes it from live-state siblings like argocd_get_managed_resources or argocd_get_resource, though no sibling is named.

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

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

The description gives no when-to-use guidance, no exclusions, and never names an alternative (e.g. argocd_get_managed_resources for live objects, argocd_get_application for app metadata). An agent must infer the selection criteria from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return shape and the empty-state behavior ('Returns {"phase": null} when no operation has run'), which is meaningful given 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?

Two tightly packed sentences, front-loaded with what is retrieved and followed by the exact empty-state return. No filler and every clause earns its place.

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

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

For a read-only getter with no output schema, the description supplies the essential return content and even the null edge case. It falls slightly short by omitting how it relates to sibling operation tools and any permission/error context, but nothing critical to invoking it 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 the schema fully documents all four parameters (name, project, app_namespace, include_resources) including their scoping and default semantics. The description adds nothing about them; baseline 3 applies when the schema does the heavy lifting.

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

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

States a concrete verb and resource ('Get the current or last sync operation') and enumerates what it returns (phase, initiator, per-status result counts). The purpose is unambiguous, though it never explicitly distinguishes itself from siblings like argocd_wait_for_operation or argocd_get_application_history.

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

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

There is no when-to-use guidance and no mention of alternatives. An agent is left to infer that this is for inspecting an existing operation rather than waiting for one (argocd_wait_for_operation) or terminating one (argocd_terminate_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 establish readOnly/idempotent/openWorld, but the description adds real behavioral value beyond them: it discloses the return shape (per-line pod + timestamp, pods seen, shown_lines count) and the termination behavior ('stops at the stream's last marker', never follows). That materially helps an agent interpret results and avoid expecting a live stream.

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, front-loaded with the verb and the most important constraint ('never follows'), then the return format. No filler; every clause earns its place.

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

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

For a 14-parameter read tool with no output schema, the description usefully compensates by describing the returned structure and the stream-termination behavior, while annotations cover safety. What remains thin is routing/selection guidance, but the core call contract is complete.

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

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

Schema coverage is 100% across 14 well-described parameters, so the schema carries the semantics. The description adds no parameter-level meaning (nothing on filter, tail_lines, previous, since_seconds, or pod_name vs kind+resource_name selection), 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?

Clear specific verb+resource: 'Get container logs (never follows)'. The parenthetical immediately delimits scope (snapshot, not streaming). It does not explicitly distinguish from sibling tools, but no sibling in the list retrieves pod logs, so ambiguity is low.

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 explicit when-to-use guidance, no named alternatives, no prerequisites. The 'never follows' clause implies a non-streaming snapshot, but the agent is not told when this is preferable to any other log/observability path, nor what conditions select 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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: role token values (jwtTokens) are never returned, only a count. It stops short of noting error behavior for a missing project or any size/rate considerations.

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 returned-content summary front-loaded and the redaction caveat immediately after. No filler or restated boilerplate.

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 usefully enumerates what the response contains and flags the jwtTokens redaction, which is the main gotcha for this call. It is nearly sufficient for a read-only getter; only error/not-found behavior and the effect of 'full' are left 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 description coverage is 100% — 'full' is documented as raw vs slim payload and 'include_roles' already carries the '(never jwtTokens)' note — so the schema does the heavy lifting. The description's token note reinforces but does not extend parameter meaning, and the 'full' parameter is not addressed in prose. 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 ('Get') and resource ('a project') and enumerates the payload contents (allowed repos, destinations, whitelists/blacklists, roles), which is more than a restatement of the name. It does not explicitly distinguish itself from the sibling argocd_list_projects, though the get-vs-list contrast is inferable.

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 offers no when-to-use guidance, no prerequisites (e.g. permissions, existence of the project), and no routing to alternatives such as argocd_list_projects for enumeration. Usage is only inferred from the verb and required 'name' parameter.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds a genuinely useful behavioral detail beyond the annotations and schema: branches and tags are paged independently, each with its own counts, which changes how an agent should drive limit/offset.

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 verb and resource, and the non-obvious paging nuance is attached to it. Nothing is wasted and nothing essential is buried.

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

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

For a read-only, annotated tool with no output schema, the description covers purpose and the key paging behavior. It omits any indication of the response shape (e.g. whether counts are totals or page-local) and any permission/auth context, but these are minor omissions 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 100%, so the baseline is 3, and the description earns an extra point by clarifying that the paging window applies separately to the branch list and the tag list. It adds no guidance on app_project scoping or force_refresh caching, which are covered only by 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 (get) and resource (a repository's branches and tags), which separates it from sibling listing tools like argocd_list_repositories or argocd_list_repository_apps. It does not explicitly name a sibling, so it stops just 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 says what is returned but gives no when-to-use guidance, no prerequisites (e.g. that repo must be registered in Argo CD), and names no alternatives for retrieving revision information. The agent must infer the context entirely.

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 openWorldHint, so safety is covered. The description adds genuine behavioral detail the annotations do not: the returned payload is slimmed, with managedFields and the last-applied annotation stripped, which maps directly onto the `full` flag's tradeoff.

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 verb and resource, and every clause earns its place by qualifying what the manifest is and how it has been modified.

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 convey the return shape, and it does so usefully (live manifest minus managedFields and last-applied). It omits error/empty behavior and pagination-irrelevant details, but those are handled by parameter descriptions for this single-object read.

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% across all 9 parameters, including edge-case behavior like project-driven 404/403 and namespace defaults, so the schema carries the burden. The description adds only indirect meaning to `full` via the mention of stripped fields; it documents no parameter syntax itself, 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 (get), a precise resource (a single managed resource's live manifest), and the transformation applied to the output. It is clearly distinguishable in intent from manifest-listing siblings, though it never names an alternative to differentiate itself from argocd_get_manifests or argocd_get_managed_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?

There is no explicit when-to-use guidance, no conditions, and no named alternative among the many sibling getters (get_manifests, get_managed_resources, get_resource_tree). The reader must infer from 'live manifest' that this fetches the cluster-side object rather than the desired-state manifest.

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

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

Annotations already declare read-only, idempotent, open-world behavior, so the safety profile is covered. The description adds valuable behavioral detail beyond that: which fields are dropped (networkingInfo, uid, resourceVersion) and that kind/health filtering is client-side. It does not mention pagination defaults, but the schema covers those.

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: output shape first, then what is dropped, then filtering behavior. Every clause adds information with no filler.

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

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

For a read-only tree fetch with a full schema and no output schema, the description covers what the tool returns, what it omits, and the filtering model. The main missing piece is how it relates to the sibling managed-resources tool, but that is a usage-guideline gap rather than a completeness gap for calling 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 every parameter is already documented. The description reinforces that kind and health_status are client-side filters, which is a minor addition. Baseline 3 is appropriate since the schema carries the 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?

States a specific verb (Get) and resource (live resource tree) and immediately characterizes the output as 'slim nodes (kind, name, health, images, parent)'. This distinguishes it from argocd_get_managed_resources and argocd_get_resource, which return different shapes.

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 usage by describing output shape and client-side filtering, but does not state when to pick this tool over argocd_get_managed_resources or argocd_get_resource. No explicit exclusions or alternatives are named.

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 openWorldHint, so safety/idempotency are covered by structured data. The description adds the set of returned fields, which is genuinely useful given no output schema exists, but says nothing about failure modes (e.g., invalid revision) or the effect of project/version_id on lookup.

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

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

A single front-loaded sentence with no filler; the most important information (what is fetched) leads. Slightly terse — it allocates no space to usage or behavioral context.

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

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

For a read-only lookup with full schema coverage and annotations, the remaining need is knowing what comes back — and the description enumerates the returned fields, compensating for the absent output schema. Error behavior and revision-format expectations are the only notable gaps.

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

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

Schema description coverage is 100%, with each of the six parameters already documented (including the 404/403 semantics of project). The description adds no parameter-level meaning 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 ('Get') and resource ('commit metadata for a revision') and enumerates the returned fields (author, date, message, tags, signature info). No sibling tool covers revision/commit metadata, so the boundary is implicitly clear, though it never names 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 description offers no when-to-use guidance, prerequisites, or alternatives — it only describes the payload. An agent gets no signal about when this is preferable to, say, argocd_get_application_history or argocd_get_manifests.

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 openWorldHint, so the safety profile is covered. The description adds genuine behavioral context by disclosing that the slim view intentionally drops OIDC/Dex config and UI banner fields, which tells the agent what data it will not receive.

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 crisp sentences, front-loaded with the primary purpose and then the slim-view caveat. No filler or redundancy.

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

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

No output schema exists, but the description enumerates the returned fields and explains the slim/full distinction, so an agent knows what it will get. It does not cover auth requirements or failure behavior, a minor gap for a read-only getter.

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 'full' parameter is already described in the schema. The description nonetheless reinforces the semantics by contrasting the raw payload with the 'slim view' and the fields it omits, adding meaning beyond the schema's terse wording.

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 ('Get') plus resource ('server settings') and enumerates the returned fields (URL, enabled features, tracking method, plugin names). This is clearly distinct from the cluster/repo/app-oriented siblings in substance, though it never names or contrasts an alternative 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 when-to-use guidance, no prerequisites, and no direction on when to prefer the slim view versus setting full=true. The agent is left to infer usage entirely from the field list.

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 openWorldHint, so the safety profile is covered. The description usefully discloses the shape of the result (sync-now status, active windows, assigned windows), but says nothing about permissions, error behavior, or rate limits beyond what the schema notes.

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

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

A single front-loaded sentence with no filler; the sync-now verdict precedes the enumeration of window sets, which is the right order for an agent scanning the 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?

There is no output schema, so the description takes on the job of hinting at the return contents, and it does so concisely. For a read-only lookup with fully documented parameters it is nearly complete, though it omits any note about what an empty or absent window set means.

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 explains 'name' (including namespace/name form) and the project/app_namespace semantics and their 403/404 implications. The description adds no parameter-level meaning, which is the expected baseline when the schema does the work.

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

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

The description names a specific verb (Get) and resource (sync windows) scoped to an application, and further specifies the content returned: whether it can sync now plus active and assigned windows. That distinguishes it from every sibling in the list, none of which deal with sync windows.

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 'whether it can sync now' implies the motivating use case (deciding or explaining sync eligibility), but the description never states when to prefer this over, say, argocd_get_application or argocd_sync_application, nor does it mention prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds value beyond them by disclosing the actual return payload (username, groups, logged-in status, token issuer), which is meaningful since no output schema exists.

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

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

A single front-loaded sentence with no filler; every clause names a distinct returned field. Nothing to trim.

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

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

With no output schema and no parameters, the description carries the burden of describing the response and does so adequately by listing the key fields. It does not mention error/auth-failure behavior, but for a simple read-only identity lookup this is minor.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is empty and fully covered.

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 ('Get') and resource ('the authenticated identity') and enumerates the returned fields, so the agent immediately knows this returns the caller's own user context. It is effectively unique among siblings, but it never explicitly contrasts itself with neighbors like argocd_can_i or argocd_get_settings, which also touch auth context.

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 it should call this when it needs to know who it is authenticated as, but there is no stated condition, prerequisite, or exclusion relative to alternatives. No guidance on when this is preferable to argocd_can_i for permission checks.

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 openWorldHint, so safety and repeatability are covered. The 'connectivity probe' framing adds modest context beyond that, but nothing is said about auth requirements or what the version payload 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, value front-loaded with the return content first and the probe framing second. Every phrase earns its place with no 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 no-parameter read tool with no output schema, the description says what it returns (server version plus bundled tool versions) and when it is useful. It is nearly self-sufficient; only the response shape remains unspecified, which is minor given the tool's simplicity.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter detail is expected or needed here.

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

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

States a specific verb and resource ('Get the Argo CD server version') plus the payload ('its bundled tool versions'). No sibling in the list retrieves version information, so the agent can distinguish it immediately from get_settings, get_userinfo, and the rest.

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 connectivity probe.' gives a clear situational context for calling it — as a lightweight liveness/connectivity check. It does not name alternatives or exclusions, but no sibling overlaps, so there is little to route away from.

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 mark this as a non-readOnly, idempotent, non-destructive operation. 'Removes nothing real' adds genuine value by reconciling the apparent write (readOnlyHint=false) with destructiveHint=false and reassuring the agent that the cache drop is safe and repeatable. It doesn't mention scope (whole cluster vs. one app) or any auth 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 filler, with the effect front-loaded before the corrective guidance. 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 one-parameter tool with no output schema and annotations covering the safety profile, this is nearly complete — the symptom it fixes and its harmlessness are both stated. A note on scope or the expected result (e.g., subsequent refresh behavior) would close the remaining 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 the single 'cluster' parameter already documents the name-or-server-URL format. The description adds no parameter 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?

Specific verb (invalidate) plus resource (cluster's cached resources) that no sibling shares — the other tools read or mutate applications/clusters directly, none invalidate cache. An agent can distinguish this from argocd_get_cluster or argocd_sync_application immediately.

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?

States the trigger condition explicitly: 'the standard fix for phantom OutOfSync or Unknown health.' That tells an agent when to reach for it, but no alternatives are named and no exclusion (e.g., don't use when the app genuinely is OutOfSync) is given.

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

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

Annotations already declare readOnly, idempotent, open-world, so the safety profile is covered. The description goes beyond them by disclosing that the upstream list endpoint has no paging, that results are sorted by name and sliced locally to satisfy limit/offset, and that four filters run client-side — non-obvious latency and result-ordering behavior an agent should know.

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: the first front-loads what is returned, the second carries the behavioral caveats. No filler, and the most decision-relevant fact (slim output shape) comes first.

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 compensates by naming the returned fields. Combined with the client-side filtering and slicing notes, an agent has enough to call it correctly; only the interaction between defaults (limit 50 / offset 0) and the name-sorted slice is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a distinction the schema does not: sync_status, health_status, destination, and name_prefix are applied client-side rather than server-side. That is real semantic value about filter cost and correctness beyond the per-parameter descriptions.

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 ('List applications') plus an enumeration of the returned row shape (name, project, sync/health, source, destination, policy), which is unusual and useful detail. It is trivially distinguished from singletons like argocd_get_application or argocd_list_repository_apps by its scope.

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

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

The description implies the tool's role (filtered bulk listing) but never states when to prefer it over siblings such as argocd_get_application for a single app or argocd_list_repository_apps for a repo view. No exclusions or prerequisites are given, so usage is only inferable.

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=true, idempotent=true, openWorld=true, so safety is covered. The description adds that rows are 'slim' and names the included fields (generators, strategy, health, conditions), which is useful. It doesn't mention pagination behavior or default limit effect beyond what the schema states.

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

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

One tight sentence, field list front-loaded, zero 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 simple read-only list tool with a fully documented schema and no output schema, the description is minimally adequate. It omits what happens with pagination, the default limit of 50, and what 'conditions' looks like, but annotations carry the safety profile.

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 every parameter is already documented. The description does not add syntax or semantics for projects/selector/namespace filtering beyond naming them indirectly. Baseline 3 is correct.

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 (ApplicationSets), and names the sibling it differs from implicitly via 'slim rows' vs get_applicationset's detail. An agent can tell this is a list/discovery operation distinct from argocd_get_applicationset.

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 'List' and the slim-row framing, but the description never explicitly says when to use this vs argocd_get_applicationset or argocd_generate_applicationset. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds a genuinely useful behavioral fact beyond the structured fields: the cluster credential config is never returned, which tells the agent not to hunt for secrets here. It does not discuss pagination limits or result ordering.

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. The positive capability is stated first and the exclusion follows, which is a sensible front-loaded order.

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 usefully enumerates the returned fields and flags the one thing that is withheld. Annotations cover the safety profile and the schema covers all parameters, so the definition is nearly self-sufficient, though it omits paging behaviour for a defaulted limit/offset pair.

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 name, server, limit and offset are all documented in the schema itself. The description adds no filter syntax, matching rules, or paging guidance beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('List clusters') and goes further by naming the shape of each row (connection state, server version, app and cache counts). It does not explicitly contrast with the sibling argocd_get_cluster, though 'slim rows' implies that a fuller single-cluster view lives elsewhere.

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 verb and the 'slim rows' framing, which suggests reaching for argocd_get_cluster when full detail is needed. There is no explicit when-to-use statement, no mention of when this is preferable to the sibling tools, and no stated prerequisites.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds the useful detail that returned rows are a 'slim' projection with counts rather than full project objects, which is genuine extra context, though it says nothing about pagination defaults or result caps.

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 no waste, front-loaded with the verb and resource and the row-shape detail appended. Appropriately sized for a simple 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?

There is no output schema, so the description does carry some burden for describing returns, and it partially discharges that with the 'slim rows' preview. However, it omits pagination behavior and the fact that name filters to a single project, leaving an agent to infer these from the schema alone.

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 name, limit, and offset each documented inline including the 1-200 bound on limit. The description adds no parameter meaning 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 (List) and resource (projects), and the parenthetical previews the row shape (repo/destination counts, role names, sync-window count). It is clearly distinguishable from argocd_get_project by the listing scope, 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?

No guidance on when to use this versus argocd_get_project (single project) or the many other list_* siblings. Nothing about filtering by name, paging, or when the slim projection is preferable. Usage is only implied by 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 declare readOnlyHint, openWorldHint and idempotentHint, so safety is covered. The description adds genuinely new context: credentials are never returned, and has_credentials signals whether any exist, which is security-relevant output semantics not present in the 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 compact sentences; the return-shape fact is front-loaded and the credential constraint follows immediately. No filler.

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

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

With no output schema, the description usefully characterizes the response (slim rows, connection state, has_credentials) and the credential exclusion. Paging behavior and the distinction from repository-adjacent siblings remain unaddressed, but the essential call information is present.

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 five parameters (repo, limit, offset, app_project, force_refresh) are already documented in the schema. The description adds no filtering, paging, or refresh semantics beyond that, 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 ('List repositories') and adds scope detail: 'slim rows and connection state'. An agent knows exactly what the tool returns at a high level. It stops short of naming or distinguishing itself from repo-related siblings like argocd_get_repository_refs or argocd_list_repository_apps.

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

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

No guidance on when to use this tool versus the repository-adjacent siblings, and no prerequisites or exclusions stated. Usage is only inferable from the tool name itself.

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 openWorldHint, so the safe-read profile is covered. The description adds that results are application paths with their config type, which tells the agent roughly what comes back, but says nothing about pagination or repository access requirements despite the openWorldHint network call.

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

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

A single sentence with the list action and scope front-loaded and zero filler. Nothing could be trimmed without losing 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?

With no output schema the description carries some burden for describing returns, and it only gestures at the result shape (paths plus config type) without saying how revision/app_project filtering affects results. For a 5-parameter discovery tool it is adequate but leaves clear gaps.

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

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

Schema description coverage is 100%, so all five parameters (repo, limit, offset, revision, app_project) are already documented in the schema. The description adds no syntax, format or scoping detail beyond that, 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 ("List") and resource ("application paths ... discoverable in a repository"), and notes the config-type detail returned. It implicitly separates itself from sibling list tools like argocd_list_repositories (repos, not apps within a repo), but never makes that distinction explicit.

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

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

There is no when-to-use guidance, no prerequisites (e.g. credential/repo access requirements), and no routing to alternatives such as argocd_list_repositories or argocd_get_repository_refs. The agent must infer the discovery use case on its own.

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 openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond what the annotations and name provide — no note on auth requirements, whether the listed actions carry argument schemas, or error behavior when the resource doesn't exist.

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 resource, the verb and illustrative examples; no filler and nothing that could be cut without losing 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?

With 8 parameters, no output schema and a read-only list operation, the description is marginally adequate but leaves the return shape (bare action names vs. actions with parameters) and the relationship to argocd_run_resource_action unstated. Since no output schema exists, the description should carry more of that burden.

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% across all 8 parameters, including the non-obvious project/app_namespace ones, so the schema does the heavy lifting and the description adds no parameter detail. Baseline 3 is correct for a fully-documented 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 pairs a specific verb ('List') with a specific resource ('custom resource actions available on a resource') and gives concrete examples (restart, pause), so an agent knows exactly what comes back. It does not, however, explicitly distinguish itself from the sibling argocd_run_resource_action, which is the obvious adjacent tool.

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

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

There is no when-to-use or when-not-to-use guidance and no routing to alternatives such as argocd_run_resource_action. Usage is only implied by the verb 'List' — an agent must infer that this is the discovery step before running an action.

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=true, so the safety profile is covered structurally. The description adds no behavioral context beyond that — no mention of permissions, partial-failure semantics, or what a failed patch returns. Adequate but not additive.

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 waste, front-loaded with the purpose before the payload examples. Every clause earns its place.

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

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

With full schema coverage, annotations covering the safety profile, and no output schema to explain, the description supplies the missing payload guidance. It could go further on merge-vs-json patch implications, but nothing essential for calling the tool is absent.

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 earns extra credit by supplying concrete patch payload examples for the required 'patch' string parameter — exactly the kind of syntax the schema's 'JSON patch body' line does not convey. This is genuine value beyond the structured fields.

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 ('Patch an application') and adds the routing phrase 'the one tool for every update', which distinguishes it from create/delete/sync/rollback siblings. It stops short of naming a specific sibling, but the scope claim is clear.

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 'the one tool for every update' plus two concrete examples (change targetRevision, disable auto-sync) give a clear sense of when to reach for this tool. No explicit when-not or negative routing is provided, so it isn't a full 5.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses that the tool pre-reads the app and returns an actionable error before failing, and warns that Git is left diverged after the re-apply. These are non-obvious behaviors an agent can't get from the annotations or 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?

Three short sentences, zero waste, front-loaded with the core action and its destructive nature. Each sentence earns its place by adding a distinct constraint or warning.

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

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

For a destructive mutation with full annotation coverage and a fully documented 8-param schema, the description covers the key failure mode and side effect. It omits what a successful rollback returns, but with a rich schema and safety annotations 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%, so all 8 parameters (including wait, prune, dry_run, project, timeout_seconds) are already documented in the schema. The description implies the history_id target but adds no syntax or semantics beyond the structured fields, 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?

Clear verb+resource: 'roll back to a prior deployment history entry' precisely names the action and the target, with 'destructive' flagged up front. It is distinguishable from siblings like sync_application conceptually, but no sibling is named to make the routing 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?

Provides a real precondition/exclusion: rollback is refused while auto-sync is on, and gives the post-rollback remedy ('fix Git afterward'). Clear context, though it never names an alternative tool for the auto-sync case, 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?

The annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true; the trailing word 'destructive' merely repeats a structured field rather than adding context. With annotations present the bar is lower, but nothing is said about what state is destroyed, whether actions are reversible, required permissions, or side effects on the running workload.

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 verb and scope front-loaded and zero filler. It is efficient, though the terseness leaves gaps that concision was traded against.

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 10-parameter mutation with no output schema, the description is thin: it does not indicate that name/action/kind/resource_name are all required, nor that the action must exist for the target kind. The annotations do carry the safety profile, and the schema is fully documented, so the gap is moderate rather than severe.

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 parameter is already documented, and the baseline is 3. The parenthetical examples loosely connect kind/action pairs ('restart' with Deployment, 'pause' with Rollout), which adds marginal mapping value, but nothing is said about how the free-form 'parameters' object should be populated.

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 (Run) and resource (custom resource action) and grounds it with two concrete examples (restart a Deployment, pause a Rollout). It does not, however, explicitly separate itself from the sibling argocd_list_resource_actions, which is the natural point of confusion for an agent picking between 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?

There is no guidance on when to use this tool versus alternatives. An agent is not told to check argocd_list_resource_actions first to discover valid action names, nor what preconditions (sync state, app health) must hold for an action to succeed.

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 readOnlyHint=false, but the description goes further by naming what actually causes destruction (prune deletes resources no longer in Git, force recreates on conflict) and the authorization requirement for revision overrides. It also discloses return behavior (started operation vs. final with wait=True), which is meaningful for a long-running 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?

Three short, front-loaded sentences with no filler: purpose first, then the destruction rationale, then return/RBAC notes. Every sentence carries information not present elsewhere.

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 13-parameter mutating tool with no output schema, the description covers the essential risks, return semantics, and one key permission gate, and annotations cover the safety profile. It stops short of describing error behavior or how dry_run interacts with wait, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, including the override-RBAC note on revision and the wait flag. The description's added value is limited to clarifying the wait return semantics, which is helpful but marginal; 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 ('Sync an application'), which is clear and distinguishes it from read-oriented siblings like argocd_get_application or argocd_list_applications. It does not explicitly name the nearest mutating siblings (argocd_rollback_application, argocd_terminate_operation) to disambiguate when sync vs rollback is appropriate.

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 flags the destructive conditions ('prune and force can delete or recreate resources') and the RBAC prerequisite for revision overrides, which implies usage context. However, there is no explicit when-to-use vs alternatives guidance (e.g., use dry_run to preview, or argocd_wait_for_operation to poll) and 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 destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds the operational scenario (hung sync) but does not disclose what termination does to in-flight resources or partial sync state — useful context that 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?

Two short sentences, zero filler, with the action introduced first and the usage hint immediately after. Every sentence earns its place.

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

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

With annotations carrying the safety profile, a complete schema, and no output schema, the description covers the essentials for a straightforward terminate call. It could still note the resulting application state after termination, but nothing blocks correct invocation.

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

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

Schema description coverage is 100%, so name, project, and app_namespace are fully documented in the schema, including the 404/403 semantics for project and the ARGOCD_APP_NAMESPACE default. The description adds nothing 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 specific verb and resource ("Terminate the running sync operation"), which is clearly distinct from siblings like argocd_sync_application, argocd_rollback_application, and argocd_wait_for_operation. It stops short of explicitly naming the closest sibling (wait_for_operation) to sharpen the distinction.

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

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

Gives a concrete triggering condition: "Use to unstick a sync hanging in Running." That is a clear when-to-use signal, but it names no alternatives or when-not-to-use cases (e.g., what to do with a healthy running sync).

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the description earns credit for going further: it discloses that timeouts never surface as errors and that the response carries timed_out=true with the latest operation, sync, and health. That error-semantics disclosure is exactly the kind of behavior annotations cannot express.

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

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

Two sentences, no filler. The terminating behavior is front-loaded and the non-obvious timeout guarantee is stated immediately after, with nothing 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 correctly compensates by naming the returned fields (operation, sync, health) and the timed_out flag, plus the terminal-phase semantics. It stops short of enumerating which phases count as terminal, which would be the last missing piece for an agent interpreting the result.

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 parameter (name, project, app_namespace, timeout_seconds, poll_interval_seconds) is already documented with ranges and defaults in the schema. The description's mention of 'timed out' loosely ties to timeout_seconds but adds no format, interaction, or defaulting detail beyond the schema. 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 (poll an application's operation) along with the three termination conditions: terminal phase, disappearance, or timeout. This is clearly distinct from a one-shot read like argocd_get_operation, though it never names that sibling explicitly to close the loop.

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 must infer that this is the tool to call after triggering argocd_sync_application, argocd_rollback_application, or argocd_run_resource_action in order to block on completion. There is no explicit when-to-use, when-not-to-use, or named alternative such as argocd_get_operation for non-blocking checks.

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