hub_operator

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

With no annotations, the description must carry the burden of behavioral disclosure. It reveals that if no card exists, the tool returns a scaffold and instructions for creation. It also implies a read-only nature through the 'never edit' guidance. However, it does not describe the exact return format, whether it only reads, or any other side effects, leaving some ambiguity.

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 composed of three sentences and is fairly concise. It front-loads the definition of the operator card, then adds context and the return behavior. It could be tightened by leading with the action verb, but it avoids unnecessary verbosity.

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 tool with no parameters and no output schema, the description gives a good sense of the concept and the fallback behavior. It clarifies that the operator card is a special, stable resource and that a scaffold is returned if missing. It does not detail the structure of the returned scaffold, but the complexity is low, so this is sufficient.

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 has zero parameters, so there is nothing to explain. Per the rubric, the baseline for 0 params is 4. The description adds no parameter information, but none is needed.

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 focuses on the operator card and its contents (facts, preferences, boundaries), and states that it returns a scaffold if no card exists. However, it never uses a direct verb like 'get' or 'read', so the action is implied rather than explicit. It does distinguish from siblings by describing the unique nature of the operator card.

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 about when this tool is relevant: the operator card belongs to no project and changes slower than other data. It also instructs agents to read Boundaries and never edit them, which implies a read-only usage. However, it does not explicitly state when to use this versus a sibling tool like hub_get or hub_context, nor does it mention any exclusions.

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