search_devices

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

Annotations indicate destructiveHint=true and readOnlyHint=false, but description focuses on search and returns, not mentioning any destructive potential. It does not contradict annotations but fails to add context about why the tool is considered destructive. Adds useful behavioral details like query syntax and default limit.

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?

Description is reasonably concise given the complexity of MongoDB query syntax, with well-organized examples and limitations. Could tighten some phrases, but overall efficient.

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 no output schema, description explains return format ('JSON array of matching device documents'), covers query syntax, limit behavior, and limitations. For a search tool with 2 parameters, this is complete and actionable.

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%, baseline 3. Description adds value beyond schema with query examples, explanation of ._value auto-append, default limit behavior, and limitations. This enriches understanding of both 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?

Description clearly states verb ('Search'), resource ('CPE devices'), and scope ('using MongoDB-style query filters'). It distinguishes from sibling tools like get_parameter or reboot_device by specifying the search functionality.

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?

Describes when to use: 'find devices by tag, manufacturer, model, firmware version, last inform time, or any other TR-069 parameter.' Provides examples and mentions limitations (no complex aggregation). Does not explicitly exclude use cases, but implicitly guides via examples.

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