mock_setup_host

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

Without annotations, the description fully discloses the tool's side effects: writes rules into Charles config, makes a backup first, and explicitly declares it never quits or starts Charles. It flags the critical constraint that apply=true only works while Charles is closed and explains the user's required manual steps. This is comprehensive behavioral transparency for a mutation tool.

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 well-structured: opens with the core purpose, explains the operational model (present/absent files), contrasts the apply modes, then lists side effects and prerequisites. Every sentence adds essential value, and the critical user action is saved for the end without wasting words. It is long but justified by the tool's complexity.

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?

Considering the presence of an output schema, the description covers all necessary operational aspects: setup steps, behavioral expectations, prerequisites for apply=true, and post-write actions. There is no obvious missing information an agent would need to safely and correctly invoke this tool. The output schema handles the return details, so the description's completeness is high.

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?

Overcomes the 50% schema coverage by providing rich context: 'host' is a bare hostname without scheme or port (complementing the schema's examples), and 'apply' is explained in detail—false gives manual steps, true writes to config with the caveat that Charles must be closed. This adds substantial meaning beyond the basic schema properties.

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?

States a specific verb ('setup') and resource ('host'), precisely describing the one-time initialization action of creating a mock directory and Charles rules for Map Local and Rewrite. Distinguishes itself from siblings like mock_route_setup by emphasizing one-time host-level setup, making the tool's purpose clear and unambiguous.

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?

Provides explicit when-to-use: 'One-time setup per host' followed by 'After that, mocks are plain files...' which implies when not to use (only once). Also clearly states the difference between apply=false (manual steps) and apply=true (writes to config) and signals prerequisites (Charles must be closed) and sequence (user must save, quit, then start). This is exceptional guidance for an agent to decide when to invoke this tool.

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