get_app_config

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: runtime vs disk config, inclusion of runtime.exs overrides, env var substitutions, and dynamic Application.put_env changes. This goes beyond a simple 'get' and helps the agent understand what to expect. However, it does not mention return format or error behavior, which is a minor gap.

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 well-structured and front-loaded. The first sentence defines the tool, followed by a useful clarification, then crisp WHEN TO USE/NOT FOR directives. Every sentence adds value with no fluff.

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 config retrieval tool with no output schema, the description is complete. It explains the tool's scope, distinguishes it from disk config, provides alternatives, and implies the typical use cases. The absence of output schema is compensated by describing the content of the runtime config.

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 does not add parameter-specific details beyond what the schema already provides, but it does contextualize usage ('check config values for ports, feature flags, module settings'), which slightly reinforces the semantic meaning of app and key.

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 the tool's function with a specific verb and resource: 'Get runtime application configuration'. It distinguishes itself from similar tools by clarifying 'what the BEAM actually has loaded (not what's in the config files on disk)', which sets it apart from other inspection tools like get_system_stats and get_process_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?

Explicit WHEN TO USE and NOT FOR sections are provided, naming exact alternatives for excluded cases: 'System health metrics (use get_system_stats)' and 'Process-level inspection (use get_process_info/state)'. This gives the agent clear routing guidance.

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