aiworkhub_dashboard_source_graph_settings_update

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

With no annotations, the description carries the full burden and does well: it discloses optimistic locking against expected_revision, atomic rewrite of the ignore policy file, and the side effect of triggering an immediate Source Graph refresh when the feature is enabled. It stops short of stating permission requirements or whether a failed revision check leaves the file untouched beyond 'fail closed' in the schema, so not quite 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?

Front-loads the verb and resource in the first line, then follows with usage routing and behavioral guarantees. Dense but every clause carries information; the single long final sentence with three comma-joined guarantees is slightly harder to scan than it could be.

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

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

Two required parameters at full schema coverage, an output schema handling return values, and a description that covers purpose, alternatives, locking semantics, and the refresh side effect. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by framing expected_revision as an optimistic-locking guard and clarifying that language_changes targets the ignore policy. It doesn't add syntax detail for the language ID keys, which remains in the nested schema description.

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 (atomically update), a specific resource (per-language Source Graph indexing switches), and scope (active repository). The 'USER WRITE' prefix immediately signals the operation class, and an agent can distinguish this from the settings/feature-switch siblings without opening any schema.

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

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

Explicitly names when to use this ('enable or disable individual languages in the Source Graph ignore policy') and routes to the correct alternatives: aiworkhub_dashboard_settings to read the current policy and revision first, and aiworkhub_dashboard_settings_update to toggle the top-level feature switch. When-to-use, prerequisites, and alternatives are all covered.

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