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

Annotations already mark the tool readOnly, and the description adds meaningful behavioral detail beyond that: it explains the source/dest orientation rule for Generalization connectors, role fields that remove directional ambiguity, and feature links indicating attached attributes or operations. This materially helps an agent interpret results correctly.

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 compact yet dense, leading with the core action and then adding only the essential disambiguation rules. Every clause earns its place; there is no filler or repetition of schema details.

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?

With no output schema present, the description compensates by explaining the key output fields (source, dest, role, feature links) and the connector orientation conventions. For a read-only relationship listing with three parameters, this is sufficient for an agent to select and invoke 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 parameters are already documented. The description adds value by showing how to use direction and connectorType together to achieve specific outcomes, and by clarifying Generalization source/dest semantics. It does not deeply elaborate on elementId, but the schema already defines it as Object_ID.

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 opens with a specific verb and resource: 'Get all relationships (connectors) for a given element.' It clarifies what a connector entry contains (source, dest, type) and distinguishes this tool from element/package/diagram sibling tools by focusing on relationship traversal rather than element retrieval or search.

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 gives concrete use conditions: filter by connectorType and direction to list direct children via incoming Generalization or direct parents via outgoing Generalization. It cites the 'without a diagram' context, which points to when this tool is preferred, though it does not name a specific sibling alternative to use instead.

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

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

The annotations already mark this as read-only, and the description adds meaningful behavioral context: Note objects are included, connectors carry feature-link resolution, and the connector list is the union of explicit and implied connectors. This goes well beyond what the annotations alone convey, though return format details are not described.

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 three sentences with no fluff. It front-loads the core purpose, then adds necessary nuances about Note objects and connector resolution. Every sentence earns its place.

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 single-parameter read-only tool with no output schema, the description is remarkably complete. It tells the agent exactly what the response will contain (diagram, elements, connectors), clarifies important inclusion rules, and explains connector semantics. No critical invocation or interpretation details are missing.

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%, and the diagramId parameter is already documented as 'The Diagram_ID to get elements for.' The description reinforces that the tool targets a specific diagram, but it does not add substantial new meaning beyond 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 uses a specific verb ('Get') and resource ('all elements and connectors placed on a specific diagram') and clearly distinguishes itself from siblings like ea_get_element (single element) and ea_list_elements (likely model-wide listing). It unambiguously states the scope of the tool.

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 clearly implies use when an agent needs everything on a diagram, including elements and connectors. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough that an agent can select it appropriately among the sibling tools.

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

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

The description goes well beyond the read-only annotation by exposing two non-obvious behaviors: the multiplicity inference caveat (and the _meta.multiplicityIsUniform flag) and the truncation semantics (attributesTruncated/operationsTruncated and totals). These are critical for correct interpretation and are not derivable from annotations or schema.

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: the first provides the main purpose (front-loaded), the second packs essential warnings. While long, every clause carries important operational guidance (multiplicity, truncation counts). It is structured efficiently, though it could be tightened without losing meaning.

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?

With no output schema, the description successfully conveys the response scope (Note, attributes, operations, diagrams, constraints) and the critical meta fields. It doesn't cover error cases or authentication, but for a read-only fetch tool these are less critical. The coverage is strong enough for an agent to call it 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?

The single parameter elementId is fully described in the schema as 'The Object_ID of the element to retrieve.' The description adds no additional parameter-level detail, so it doesn't extend beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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 opens with a specific verb-resource pair ('Get full details of an Enterprise Architect element by its ID') and enumerates the exact data returned (Note, attributes, operations, diagrams, constraints). This is unambiguous and clearly distinguishes it from sibling tools like ea_list_elements or ea_search, even without naming them.

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 when to use this tool—when you need full element details by ID—but it never explicitly contrasts it with siblings or states when not to use it. No exclusions or alternatives are mentioned, leaving the choice somewhat to inference.

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

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

The readOnlyHint annotation already marks this as safe, and the description adds meaningful behavior beyond that: it explains that `resolvedPath` is environment detail rather than citable, that `resolvedPathNote` clarifies this, and that configuration sources can include skipped or shadowed entries with reasons. This gives the agent realistic expectations about sensitive or non-portable output.

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 dense, run-on sentence that front-loads the core purpose and then packs in many field-level details. Every detail is relevant, but the wall of text is harder to parse than it needs to be; breaking it into a short overview plus field list would improve scannability without losing information.

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?

With no output schema and minimal annotations, the description carries the burden of explaining return values, and it does so thoroughly: it covers the identity fields, server version, resolved path and its note, configuration source and provenance, and skipped/shadowed settings. For a zero-argument read-only status tool, nothing essential is missing.

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, so the input schema fully covers the parameter surface. Per the baseline for no-parameter tools, 4 is appropriate; there is no parameter information to provide, and the description instead focuses on the output schema, which is the more important gap given no output schema exists.

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 opens with a specific verb and resource: 'Report which .qea export file the server has open.' It then enumerates the exact information returned, making its identity and scope unmistakable and clearly distinct from sibling tools that query elements, packages, or diagrams.

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 a use case—when you need to know which file the server has open or how configuration was resolved—but it never states when to use this tool versus alternatives or when not to use it. No sibling tool is named or contrasted, leaving the agent to infer placement entirely from the tool name.

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

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

Annotations already declare readOnlyHint: true, so the description doesn't need to state safety. It adds context about the return shape (id, name, parentId, elementCount) and the depth behavior, which is useful. It doesn't disclose error cases or edge behavior, but for a read-only navigation tool with these annotations, this is sufficient.

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?

Two sentences with no fluff. The primary purpose is front-loaded, followed by parameter-specific behavior and return structure. Every sentence carries useful information, and the description is appropriately sized for the tool's simplicity.

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 simple read-only tool with no required parameters, the description is complete. It explains the output node fields, the effect of each parameter, and the default/limit for depth. There is no output schema, so the return description is essential and provided. Nothing critical is missing for an agent to call this 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 description coverage is 100% – both depth and packageId have clear descriptions. The main description echoes these semantics without adding new meaning. For instance, it repeats that packageId gets children and depth controls recursion. Since the schema already documents the parameters thoroughly, the description adds minimal extra value here.

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: 'Navigate the package hierarchy.' It specifies two distinct behaviors based on parameter presence (top-level vs. children) and describes the node structure, making it unambiguous what the tool does. This differentiates it from sibling tools that list elements or search, even without naming them.

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 provides clear context for when to use the tool: with no parameters for top-level packages, and with a packageId for children. It implies the tool is for hierarchy browsing, but does not explicitly exclude alternatives or name when not to use it (e.g., when searching for a specific element). The guidance is good but not exhaustive.

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

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

Annotations already mark the operation as read-only; the description adds meaningful behavior beyond that: scenarios are parsed flows ordered by type (Basic Path first, then Alternate, then Exception), steps are numbered within each scenario, and `uses` codes are not independently searchable or resolvable. This gives the agent important runtime expectations without contradicting the annotations.

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?

Purpose is front-loaded in the first sentence, and every subsequent sentence adds necessary information about output shape, ordering, step numbering, or the constraint-lookup caveat. There is no filler and no redundant repetition of schema content.

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?

Since there is no output schema, the description takes on the burden of explaining return shape and does so well: `scenarios` contains flows with name/type/notes/steps, and each step carries stepNumber plus trigger/uses/result/state/link. It also documents ordering and the non-obvious `uses` resolution path, making the tool effectively self-contained for a single-parameter call.

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 input schema already provides 100% coverage for the single `elementId` parameter, describing it as the Object_ID of the element, typically a UseCase. The description reinforces that this ID selects whose scenarios to fetch but does not add new parameter-level details, so the baseline 3 is appropriate.

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 first sentence names a specific operation ('Get use case scenario flows') on a specific resource ('an element'), and the rest of the description defines what the result contains. It is clearly distinguishable from the sibling search/list tools because it is specifically about scenario flows for a UseCase element.

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 states this tool is for retrieving scenario flows for a given elementId, which directly implies its primary use. It also gives an explicit when-not/alternative: `uses` codes are not independently resolvable and should be looked up via `ea_get_element` on the same element's constraints. It does not compare against all sibling tools broadly, so it stops short of a 5.

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

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

Annotations already mark readOnlyHint=true, but the description adds substantial behavioral detail: it returns tables, columns, indexes, and explains the rowidAlias (INTEGER PRIMARY KEY aliasing SQLite's rowid) and its null case, plus the rowidNote. It also notes that the table form 'echoes' the table name, giving the agent a clear picture of the output beyond the annotation.

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-organized: it front-loads the dual-mode behavior, then a detailed but relevant explanation of rowidAlias/rowidNote, followed by usage guidance and a sibling reference. It is not overly verbose and each sentence adds value, though the rowid explanation could be slightly trimmed without losing meaning.

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?

With no output schema, the description carries the burden of explaining return structure. It covers the key fields (tables, columns, indexes, rowidAlias, rowidNote) and their meanings, and notes the relation to sibling tools. It is complete for an agent to understand the tool's behavior and when to invoke it, though it omits exact JSON formatting (e.g., arrays) which is minor given the explanatory depth.

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 schema covers the parameter (tableName) with its own description ('Omit to list all tables with row counts'), so baseline is 3. The description enriches this by explaining that providing tableName switches the output to columns and indexes and details the rowid fields, adding meaning beyond what the schema states.

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 action ('List the model's database tables') and the conditional behavior with a tableName to get columns and indexes. It differentiates from siblings by noting it reveals data beyond what the typed ea_* tools return and explicitly names ea_get_model_info for identity, so an agent knows exactly what this tool does and how it differs.

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 provides a clear when-to-use directive: 'Use this to discover what data the model holds beyond what the typed ea_* tools return.' It also points to the alternative for identity (ea_get_model_info), offering a distinct context. While it doesn't list explicit exclusions, the guidance is sufficient to route an agent correctly.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that ordering is stable but artificial, that adjacency carries no meaning, that continuation names the next call, and that breakdown reports type counts. These are non-obvious behavioral details an agent needs to interpret results correctly.

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?

Four dense sentences, each earning its place: purpose+filters, result fields, ordering caveat, pagination strategy, and breakdown guidance. The most important information is front-loaded, and there is no filler or repetition of the schema.

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 listing tool with no output schema, the description covers the entry fields returned, ordering semantics, pagination mechanism, and a narrowing strategy for large result sets. An agent can call the tool and interpret results correctly without additional context.

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?

With 100% schema description coverage, the baseline is 3; the description adds meaning by explaining the offset/continuation paging pattern and recommending smaller batches. It also clarifies the filtering intents (package, diagram type, name substring) and the result fields tied to the call, going slightly beyond the raw 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 opens with a specific verb and resource ('List diagrams in the model') and enumerates the optional filters (package, diagram type, name substring), which clearly scopes the operation. The result fields and ordering caveat further distinguish it from sibling tools like ea_list_elements or ea_search, even though no sibling is named.

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?

It gives practical guidance: use offset rather than larger limit for large result sets, follow continuation, and use breakdown to narrow by diagramType instead of paging. It does not explicitly compare against sibling tools such as ea_search or ea_get_diagram_elements, so the when-to-use-this-versus-alternative guidance is slightly incomplete.

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

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

Beyond the readOnly annotation, the description discloses that ordering is stable but artificial, that adjacency carries no meaning, and that `continuation` and `breakdown` appear as paging aids. This is valuable behavioral context that the schema and annotations alone do not provide.

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?

Three dense sentences deliver exactly the needed information: what is returned, how ordering behaves, and how to page. Nothing is redundant, and key behavioral caveats are front-loaded.

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?

With no output schema, the description carries the burden of explaining return values. It covers the element fields, grouping, ordering, pagination through `continuation`, and the `breakdown` mechanism, making the tool's contract clear enough to call confidently.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful usage semantics for `offset`, `limit`, and `objectType`, explaining why one pagination strategy is preferable over another and how `breakdown` should drive narrowing.

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 states a specific verb and resource ('List elements within a package') and immediately clarifies the lightweight nature of the result. It also distinguishes itself from single-element retrieval and broader search by describing exact output fields and grouping.

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?

It provides clear usage context for pagination, explaining to use `offset` rather than a larger `limit` and to narrow by `objectType` when `breakdown` indicates many matches. It does not explicitly name alternatives among siblings, but the context is clear enough for tool selection.

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

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

Although annotations indicate readOnly and closed-world behavior, the description goes far beyond that by explaining the matching algorithm in detail: exact GUID matches, name-first matching, prefix fallback, and the guarantee that exact hits are not diluted. It also warns that 'prefix' candidates are inexact and must not be treated as confirmed identities. This is rich behavioral context not available in annotations or schema.

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 dense paragraph but each sentence contributes unique value: the action, matching rules, output structure, warning about prefix, and filtering advice. It is not overly verbose, though the structure could be improved with bullets or headings. It is appropriately front-loaded with the purpose and primary behavior.

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?

Despite lacking an output schema, the description fully explains the return format: the echoed 'reference', the 'candidates' array, and each candidate's fields (type, id, name, fullPackagePath, eaGuid, match). It also clarifies the meaning of each match value and the warning about prefix matches. The matching algorithm is completely described, leaving no significant gaps for an agent to correctly invoke and interpret the result.

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 schema already documents both parameters, but the description adds meaningful semantic detail for the 'reference' parameter by explaining the matching rules (exact vs prefix) and how analyst codes like UC_ABC_2079 map to elements. For 'kind', it only restates the filter intent with little added value. Overall, the description enhances understanding beyond the schema, earning above the baseline 3.

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 resolves an analyst reference (braced GUID or plain name) to model candidates. It specifies the verb 'resolve' and the resource 'analyst reference', and the matching behavior distinguishes it from a generic search tool. The detailed matching rules make the purpose unambiguous and differentiate it from sibling tools like ea_search.

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 provides a clear context for when this tool is appropriate: it is used to resolve references to candidates, with explicit guidance on how references are matched (exact, prefix) and a warning about inexact matches. It does not explicitly name alternatives or exclusion conditions, but the resolution-specific behavior makes the use case evident. The optional 'kind' filter is also mentioned as a way to narrow results.

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

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

Annotations only carry readOnlyHint=true and openWorldHint=false; the description carries the full burden of behavior and delivers far beyond it. It discloses case/diacritic-insensitive matching, entity-encoded text handling, conjunction and phrase semantics, ranking promotion without exclusion, per-term failure diagnostics, ordering fallback, evidence capping with withheld counts, truncation flags, and descendant-scope traversal. No contradiction with the read-only annotation.

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?

Dense but disciplined — roughly 300 words with every sentence carrying new behavioral information and no restatement of schema content. It is front-loaded with the core search scope and matching semantics before moving to ranking, evidence, and pagination. A slight deduction for being one continuous block that could benefit from paragraph breaks given the breadth of topics covered.

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?

With no output schema, the description must explain return values and it does thoroughly: results ordering, per-result match evidence with source field and snippet, truncated note preview, termMatches diagnostics, continuation tokens, and breakdown distributions. For a 7-parameter search tool with conjunction semantics, ranking, and paging, nothing an agent needs to invoke it correctly is missing.

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 baseline is 3. The description adds real value on top: contiguous-substring matching rules, whitespace-as-phrase never being split, the one-entry-list behavior, per-term diagnostic reporting, and the boost-promotes-but-never-excludes ranking nuance — none of which appear in the schema. It does not need to repeat the schema's basic field semantics, so 4 is appropriate rather than 5.

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?

Opens with a specific verb and resource — 'Search Enterprise Architect model elements' — and enumerates precisely which searchable fields are covered (name, alias, notes, attribute/operation/constraint names and notes). It also differentiates itself from the sibling `ea_search_and_any_of` by explicitly stating what this tool does not do (never narrows via boost terms).

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?

Gives explicit when-to-use guidance with a named alternative and the exact condition selecting it: 'for narrowing to only elements matching an alternative too, use ea_search_and_any_of instead.' It also advises operational strategy — walk large results with offset, use breakdown to narrow instead of paging — so the agent knows how to steer the call sequence.

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

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

Even with readOnlyHint=true, the description adds substantial behavioral context: fallback `termMatches`, strongest-first ordering, truncation flags, capped and withheld match counts, continuation behavior, and breakdown distribution. None of this contradicts the annotations, and it gives the agent a clear model of how the tool behaves beyond the annotation hints.

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 long but densely packed with operational value; every clause covers either purpose, filtering semantics, alternatives, result interpretation, or pagination. It is front-loaded with the core distinction from `ea_search` and has no filler or tautological repetition.

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 7-parameter search tool with no output schema, the description covers input semantics, result shape, fallback behavior, ordering, pagination, and aggregation breakdown. The only parameters not individually expanded in prose are `objectType` and `stereotype`, but their schema descriptions are already clear enough, so nothing essential is missing.

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 the baseline is 3, but the description goes well beyond field names: it defines `requiredTerms` as conjunctive contiguous substrings that need not share a field, clarifies `andAnyOf` narrows and is inert when empty, and ties `offset` to `continuation` and `packageScope` to descendant packages. This materially helps an agent construct correct calls.

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 opens with a specific verb and resource: searching Enterprise Architect model elements, and immediately differentiates itself from the sibling `ea_search` by naming `andAnyOf` as the added filter. It clearly explains the relationship to `ea_search` so an agent can tell the two tools apart without inspecting the schema.

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?

It explicitly says when to use `ea_search` instead ('For promoting rather than narrowing'), and explains that `andAnyOf` can only ever narrow results. It also gives practical guidance for large result sets via `offset` and `continuation`, making the use conditions unambiguous.

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