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

The description discloses critical behavioral traits beyond annotations: each key is shown only once, keys are bus-only and cannot spend on inference, and limits exist per call and per project. These are exactly the kind of operational caveats an agent needs and are not visible in the annotations alone.

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 slightly longer than strictly necessary but remains tightly packed with relevant constraints and caveats. It front-loads the core purpose and every sentence contributes actionable information, with only minor redundancy like 'Flow Agent Bus:'.

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 simple schema, the presence of an output schema, and the annotations, the description covers all essential context: scope limitations, per-call and per-project limits, one-time key display, security handling, and inference restrictions. An agent has enough information to invoke the tool correctly and safely.

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 schema already documents the parameter fully, so the baseline is 3. The description adds semantic value by explaining how the key scope affects acceptable name formats, such as using simple names under a bus-scope key versus full agent://project/name with an owner key. This helps the agent form valid parameter values.

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 a specific action and resource: 'create bus keys for NEW teammates.' It clearly distinguishes the tool's scope from other bus operations by emphasizing 'NEW teammates' and 'mint,' making the purpose unambiguous and distinct from siblings.

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 gives clear context for when to use the tool: minting keys for new teammates, with scoping rules for bus-scope vs. owner keys. It does not explicitly name alternatives or exclusion conditions, but the 'NEW teammates' framing and security guidance ('never as a bus message') provide strong usage direction.

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