backfill_security_scans

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 mentions scanning 'all components in the metadata store' and the batch processing nature ('Components to scan per batch' is in schema, not description). However, it doesn't disclose critical behavioral traits: whether this is a long-running operation, what permissions are required, whether it's destructive (e.g., overwrites existing data), rate limits, or error handling. For a tool that likely performs batch operations on a metadata store, this is a significant gap.

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 extremely concise: two sentences that directly state the purpose and key parameter effect. Every word earns its place with zero redundancy. It's front-loaded with the core purpose, followed by clarifying details. This is an excellent example of efficient communication.

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 tool's complexity (batch processing of security scans), the description is incomplete. No annotations are provided to cover safety or behavioral aspects, and while an output schema exists (which helps), the description doesn't address critical context like what 'backfill' entails operationally, whether it's idempotent, or what happens during execution. For a tool that interacts with a metadata store and performs scans, more contextual information would be helpful.

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 description coverage is 0%, so the description must compensate. It explains the 'force_rescan' parameter's effect ('all components if force_rescan=True'), adding meaning beyond the schema's 'Rescan already-scanned components'. However, it doesn't mention the 'batch_size' parameter at all, leaving half the parameters undocumented. The description adds some value but doesn't fully compensate for the coverage gap.

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 states the tool's purpose: 'Backfill security scans for existing components.' This specifies both the action (backfill security scans) and the target (existing components). It distinguishes from siblings like 'security_scan' (likely for new scans) and 'security_audit' (likely for analysis rather than scanning). However, it doesn't explicitly differentiate from all siblings, so it's not a perfect 5.

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 implied usage guidance: use when components lack security data or when force_rescan is needed. It mentions the 'force_rescan' parameter to control behavior. However, it doesn't explicitly state when to use this tool versus alternatives like 'security_scan' or 'security_audit', nor does it mention prerequisites or exclusions. This leaves some ambiguity for the agent.

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