wp_get_theme_file

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

With no annotations, the description carries the transparency burden. It discloses permission requirements, path restrictions, default theme behavior, and the refusal condition under DISALLOW_FILE_EDIT. It also implies read-only semantics via 'Read', but does not mention behavior on missing files or whether raw contents are returned.

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?

All sentences contribute necessary information without redundancy. The description is about 60 words and stays focused on usage, constraints, and prerequisites. No filler or irrelevant detail.

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 lack of an output schema, the description does not specify the return format (e.g., raw text, JSON, escaped HTML) or error handling (e.g., file-not-found). It also omits the meaning of `install`, which is a required parameter in the schema. These gaps leave the agent uncertain about expected output and the role of one parameter.

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 description explains `file` (relative path, restrictions) and `theme` (defaults to active child, pass for specific theme), but provides no explanation for the required `install` parameter. Since the schema has zero parameter descriptions, the description only partially compensates for two of three parameters.

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?

Clearly states the action (read) and the resource (theme file), and explicitly distinguishes from the sibling write operation `wp_set_theme_file`. The emphasis on ACTIVE theme is clarified by noting that a specific theme can be passed via the `theme` parameter.

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 concrete usage constraints: relative path required, absolute paths and '..' refused, default to active child theme, and an optional theme parameter. Also lists prerequisites (REST transport, plugin version, app password with `edit_themes`) and a known blocker (DISALLOW_FILE_EDIT), which effectively tells the agent when this tool will fail.

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