refresh_application

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description reveals this is a state-changing operation (triggers a refresh) but doesn't disclose what happens to in-flight syncs, whether the refresh is synchronous or async (does the tool wait for completion?), rate-limit concerns, or the impact of the refresh on the application. The return/behavior after refresh completion is undocumented.

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

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

The description is compact with a one-line title and a two-line body. It front-loads the primary purpose. No redundancy or filler. It could be slightly better structured to surface the hard-refresh param guidance more explicitly, but it's efficiently written.

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 state-changing tool with no annotations and 0% schema coverage, the description does important work explaining the hard parameter. An output schema exists, which relieves the return-value explanation burden. However, key context is missing: whether this is async (ArgoCD refreshes are typically async), what happens to a currently-running sync operation, and when you'd prefer this over sync_application. These gaps are notable for a mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate. The description does explain the 'hard' parameter meaning ('invalidate cache and force full refresh'), which is genuinely helpful beyond the bare schema description. However, it doesn't clarify 'instance' (which ArgoCD instance — presumably multiple exist given the default) or 'name' semantics beyond what the schema states.

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

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

The description clearly states the action ('Force manifest refresh from Git') and identifies the resource (ArgoCD application). It distinguishes this from sibling tools by being the refresh-specific operation among read/mutate/sync tools. However, it doesn't explicitly differentiate from sync_application or rollback_application, both of which also deal with application state.

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

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

The description provides context that this triggers a manifest re-fetch, which implies it's for when the application shows stale or out-of-sync manifests. However, it doesn't give explicit when-to-use vs when-not-to-use guidance, no alternatives for manual reconcile vs hard refresh, and doesn't explain when hard=true is warranted beyond 'invalidate cache and force full refresh'.

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