Read Theme Source File

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: sandboxing to wp-content/themes, directory vs. file behavior, 500 KB cap, and plugin/admin requirements. This goes well beyond the annotations and provides clear expectations without any contradiction.

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 compact and front-loaded with the core action, followed by behavior, use case, and prerequisites. The 'Args' section is somewhat redundant with the schema's parameter descriptions, but it's brief and does not detract from clarity.

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 read-only tool with 2 parameters, rich annotations, and no output schema, the description is complete: it explains sandboxing, output behavior (file vs directory), size cap, authentication prerequisites, and a specific use case. An agent has enough context to invoke the tool correctly.

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 100%, so the baseline is 3. The description repeats path semantics and gives an example, but adds no new information about response_format beyond the schema. For path, the description's 'Omit to list themes' and 'relative to wp-content/themes' largely mirror the schema.

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 'Read theme source on the server (sandboxed to wp-content/themes)' with a specific verb and resource. It distinguishes itself from siblings like wp_list_themes by detailing path-based directory/file behavior and a 500 KB cap, making the tool's unique capability obvious.

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 a concrete use case ('Use to discover Kadence footer-builder option keys') and necessary prerequisites ('Requires Bridge plugin active + admin'). However, it doesn't explicitly mention when not to use it or compare it to alternatives such as wp_list_themes for simple theme listing.

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