read_config

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

With no annotations provided, the description carries the full burden. It discloses the parsing capability and the priority rule (path over service), and mentions file size limits via parameters. However, it doesn't disclose what happens on parse failure, permissions errors, or how auto-location resolves ambiguous service matches. It also doesn't mention that this is a read-only operation explicitly, though it's implied.

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 a single tight paragraph, front-loaded with the core action. It's concise but dense with useful info. It could mention sibling distinctions explicitly, but it's not bloated. The service list is quite long (leaning on schema) but that's in the schema already.

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?

The tool is moderately complex with 5 params and many format/service options, but schema coverage is 100% and the description adds the parsing formats, dual usage modes, and priority rule. No output schema exists, but for a read/parse tool the return value can be reasonably inferred. Auto-detection behavior from file extension is mentioned in the format param schema.

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 coverage is 100% with rich descriptions for each parameter. The description adds complementary context by naming example service names and format scenarios beyond the schema. The compactMode parameter ('keys-only') is contextualized as 'AI context saving' which adds useful intent. The description adds the priority ordering between service and path which isn't in 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 the tool reads and parses config files, lists many supported formats, and distinguishes between service-name auto-location vs direct file path. It clearly differentiates from sibling tools like read_log and discover_configs by specifying it's about config files with parsing.

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 explains two usage modes (service name auto-locate vs direct path) and notes path takes priority when both are given. It gives concrete examples like 'nginx'. However, it doesn't explicitly state when NOT to use this for alternatives, though siblings are clearly different (read_log, discover_configs, get_system_status).

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