ea_search

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

The description adds behavioral context beyond the readOnlyHint annotation by explaining that matching spans the full Slovak alphabet with encoded entity handling, and that results include a decoded note preview and a truncation flag. This provides useful insight into the tool's behavior and return format without contradicting any annotations. It could mention more about error handling or edge cases, but the provided details are valuable.

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 two sentences with no redundancy. The first sentence states the primary action and scope, and the second adds the matching behavior and return structure. It is front-loaded and every sentence contributes meaningful information. This is a model of conciseness for a tool with this complexity.

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 description is largely complete: it covers what is searched, the return format (results with decoded note preview and truncation flag), and special matching behavior (Slovak alphabet). The schema covers parameter details, and the lack of an output schema is compensated by the description of the results structure. Minor omissions like pagination or rate limits prevent a 5, but it is sufficient for an agent to call the tool correctly.

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%, so each parameter already has a description. The tool description mostly repeats the scope of the query parameter ('across all model text') and adds no new meaning for the other parameters (limit, objectType, stereotype). The baseline for full schema coverage is 3, and since the description offers no additional param-specific insight, it stays at that baseline.

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: searching Enterprise Architect model elements by various textual fields (name, alias, notes, etc.). It is specific about the resource and the search scope, but it does not explicitly differentiate from sibling tools like ea_list_elements or ea_get_element. The verb 'search' and the field list make the purpose unambiguous, though a mention of when to prefer this over a list/get operation would push it to 5.

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 implies its usage: when you need to find elements by textual content. It does not provide any explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The implied usage is clear, but the lack of explicit routing to siblings or conditions for use keeps it at a 3 rather than a 4 or 5.

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