ap_get_config

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

With no annotations provided, the description carries the behavioral burden. It discloses that the tool is read-only, enumerates what data is available, and explicitly excludes post-processing settings. It does not describe output formatting or error behavior, but for a parameterless config getter this is reasonably transparent.

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 purposeful: it front-loads the read-only nature and then provides a structured inventory of exposed preferences. The second sentence adds a valuable exclusion. It is not overly verbose relative to the amount of information conveyed.

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 parameterless getter with no output schema, the description is nearly complete: it lists the available preference categories and calls out what is absent. Minor gaps are the lack of explicit return-shape detail and failure conditions, but these are low-risk for this tool.

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 tool has zero parameters and the schema is empty, so the baseline of 4 applies. The description does not need to explain parameter semantics because there are none; it instead focuses on what the returned configuration contains.

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 identifies the tool as exposing application preferences that are readable from a plugin, and enumerates the specific preference groups included. This distinguishes it from sibling tools like ap_set_config (write counterpart) and ap_get_app_info (app-level info).

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 makes clear this is the read path for plugin-readable application preferences and explicitly lists what is included. It also says post-processing settings are not exposed, which prevents misuse. It does not explicitly name ap_set_config as the alternative for writing, but the read-only framing implies this boundary.

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