agent_graph_auditor__scan_text

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

No annotations are supplied, so the description carries the full behavioral burden. It does add real value by enumerating the dangerous tool classes it traces (shell/code-exec/file-write/network/credentials) and the delegation/group-membership propagation path. However, it says nothing about whether the scan is read-only, how findings are shaped or severity-ranked, or any limits on snippet size or supported syntax versions.

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?

A single front-loaded sentence starting with the verb and resource, followed by the clarifying em-dash gloss on what 'excessive agency' means. The parenthetical framework list and tool-class enumeration earn their space, though the sentence is long and could be split for scanning.

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 scanner with no output schema and no annotations, the description should say what comes back (findings list, severity, agent-to-agent paths). It describes the detection target well but leaves the result shape entirely unknown, which is a meaningful gap for a tool whose whole value is its findings.

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 100% with only two parameters (content and an optional label), both documented in the schema, so the schema already handles parameter semantics. The description adds no constraints on content (size, encoding, partial snippets) and does not mention the label parameter's effect on findings, so baseline 3 applies.

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?

Names a specific verb (Scan), a specific resource (a Python snippet defining a multi-agent orchestration), the frameworks it understands (LangGraph, CrewAI, AutoGen/ag2), and the exact defect class (excessive agency reachable through delegation). This is distinguishable from the sibling scan_file and scan_directory tools by the 'snippet' framing.

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?

Usage is only implied by 'Scan a Python snippet', which suggests in-memory text rather than a path. The description never explicitly routes the agent to agent_graph_auditor__scan_file for paths or scan_directory for trees, nor does it mention list_patterns for inspecting rule coverage. An agent must infer the alternative from the sibling names.

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