splithub_domains

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 that replacement is destructive, that subdomains are included, that an empty list resets to accept any origin, and that disallowed origins are dropped with 403 behavior. It does not mention auth or rate-limit considerations, but the core mutation and enforcement behavior is clear.

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 dense but efficient: it front-loads the resource, then states the no-argument behavior and the argument-based replacement behavior. Every sentence adds useful information and there is 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 explains what the no-argument form returns: all allowed domains, where they apply, which experiments/properties accept any origin, and origins seen sending events. It does not describe the response for the replacement mode, but the operational behavior is otherwise 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 67%, and the description meaningfully supplements it by explaining that kind + id + hosts together trigger replacement, that hosts includes subdomains, and that an empty hosts list clears the restriction. The id parameter is only implicitly defined as the target experiment/property, which keeps this from being a perfect score.

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 specifies the resource (allowed domains per experiment/property) and clearly distinguishes its read mode from its replace mode. It is specific enough that an agent can separate it from sibling tools such as splithub_status or splithub_analytics.

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 explicitly states the condition for listing ('Without arguments') and the condition for replacing ('With kind + id + hosts'). This gives the agent clear routing rules without needing to infer from the schema.

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