update_discover_task_state

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

No annotations are provided, so the description carries the full burden. It discloses little beyond the input example showing discoverTaskId and state='CLOSED'. It does not mention side effects, permissions, reversibility, or exact behavior—making it hard for an agent to anticipate consequences of invoking the 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?

The description is brief and includes a useful example payload, so it does not waste words. However, it is under-specified: the label-like phrasing and minimal explanatory text mean the conciseness is more a result of lack of content than thoughtful prioritization. It is not as clear or efficient as a well-crafted one-sentence description.

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

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

Given the nested input object, lack of output schema, and absence of annotations, the description is insufficient. It provides an example template but omits valid state values, the mutation's effect, and how it differs from sibling tools. An agent cannot confidently select this tool or construct a correct invocation beyond copying the example.

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 input schema only defines a generic 'input' object with a type reference, so the example in the description adds meaning by revealing the fields discoverTaskId and state. It provides one example value for state but does not enumerate all possible states or explain the semantics of each field. This adds some value beyond the schema, but not comprehensive coverage.

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 'Discover Tasks · mutation updateDiscoverTaskState' but does not clearly explain what the mutation does. It mostly restates the tool name and provides a GraphQL label, offering no specific verb or outcome beyond the vague 'update state.' The example hints at setting state to CLOSED but the purpose remains implicit.

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 is provided on when to use this tool versus alternatives like close_discover_task, assign_discover_task, or update_task_state. There are no usage conditions, exclusions, or alternative recommendations, leaving the agent to infer appropriate use.

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