OPC UA Modeler

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the authoritative standard ('UNECE Rec. 20') and a usage policy, but does not disclose details such as return shape, exact-match versus fuzzy-match behavior, or what happens when no symbol is found.

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 short sentences with no filler, and the core purpose appears first. The imperative rule is front-loaded where it matters and 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, idempotent lookup, the description covers purpose, input, and mandatory usage well. The main gap is the lack of any note about the response representation or no-match behavior, but the low complexity and existing annotations keep this from being a significant deficiency.

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 'query' parameter is fully documented in the schema with a clear description and examples. The tool description only refers to it as 'a given description', adding no significant 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 names a specific verb ('Find'), a precise resource ('official UNECE Rec. 20 engineering unit symbol'), and the input it operates on ('a given description'). It clearly distinguishes this tool from the sibling tools, none of which are engineering-unit lookups.

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 explicit when-to-use guidance: 'ALWAYS call this before using any engineering unit'. It also states a hard behavioral rule: 'NEVER guess unit symbols', which tells the agent the alternative to avoid. No sibling tool is an alternative, so no further routing is needed.

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 readOnly, idempotent, and openWorld annotations already communicate the safety profile, and the description adds context by explaining how result blocks are applied (`interfaces:` vs `addIns:`) and what distinguishes an AddIn (DefaultInstanceBrowseName). It does not detail no-match behavior or the exact response shape, but for a read-only lookup tool the provided context is 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?

Four sentences carry the entire necessary message with examples, a preference rule, technical application syntax, and a decision rule. There is no filler, and the core purpose is 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?

For a one-parameter, read-only tool with no output schema, the description covers what to pass, what to expect back, and how to apply the results. It leaves some open questions (e.g., behavior when no match is found, pagination), but those are minor for this level of complexity.

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 `query`, so the baseline is 3, but the description enriches it with additional example keywords (DeviceHealth, Location) and links the query semantics to the output decision (single property vs. sub-object). That meaningfully clarifies what kinds of inputs yield Interfaces versus AddIns.

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 action and resource: find reusable Interfaces/AddIns by capability, with concrete example keywords. It clearly says what the tool returns (standard blocks that already expose the capability), but it never names or contrasts sibling tools such as search_types or list_types, so differentiation is implicit rather than explicit.

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 instructs the agent to prefer an existing reusable block over inline redefinition, and it provides a concrete decision rule: a single property should use an Interface, while a whole named sub-object should use an AddIn. This tells the model when to call this tool and how to choose between the two result categories.

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 readOnly, idempotent, and open-world hints, so the safety profile is covered. The description adds useful context beyond annotations: it lists the content areas of the reference and states that no API key is required. This is appropriate for a no-parameter reference lookup.

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 filler. The first sentence front-loads what the tool returns, and the second delivers the usage instruction and auth note. Every clause 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 no-parameter, no-output-schema reference tool, the description is complete: it states the content scope, the recommended invocation point, and auth requirements. Combined with the annotations, an agent has everything needed to select and call this 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?

The tool has zero parameters, so the description does not need to explain parameter semantics. The schema coverage is 100% vacuously; baseline 4 applies. No additional parameter meaning is required.

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') with a specific resource ('grammar reference for the OPC UA modeler YAML DSL') and enumerates the contents (file header, sections, naming conventions, examples, mistakes). This clearly distinguishes it from sibling tools like get_type_details or opcua_model_create, which address different resources.

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 instructs 'Call this FIRST before writing any YAML model by hand', which gives a clear condition for use. It also notes that it works without an API key, implying it is a low-friction first step. It does not name alternatives or explicit when-not-to-use cases, so it falls short of the full 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 declare readOnlyHint=true and idempotentHint=true, which cover the main behavioral safety traits. The description adds that the tool returns structural details about a type, but it does not disclose additional behavioral traits such as error conditions, output format, or any special behavior. This is adequate given the annotation coverage but not rich.

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 filler. The action and resource are front-loaded, the content categories are compactly listed, and the usage guidance is the final sentence. Every clause contributes value.

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 lookup with two fully documented required parameters, the description gives enough to invoke the tool correctly and explains the intended use case. It lacks an explicit alternative-routing hint and does not describe the output schema, since none is provided, but this is a minor gap for a straightforward getter.

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 schema fully documents both parameters (alias and browseName). The description does not add parameter-level semantics beyond calling the type 'specific,' which matches baseline expectations when the schema carries the explanatory burden.

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') with a specific resource ('detailed information about a specific type') and lists concrete content categories like components, properties, methods, interfaces, and optional members. It is clear, though it does not explicitly contrast itself with siblings such as list_types or search_types, relying on 'specific type' to imply the distinction.

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 clear context: 'Use this to understand a type's structure before creating instances or subtypes.' This tells the agent when the tool is appropriate, though it does not mention when to prefer alternatives or provide exclusions.

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 and idempotentHint=true, so the safety profile is covered. The description adds scope and output content ('full names, URIs, and dependencies') but does not disclose additional behavioral traits such as pagination or ordering. It does not contradict 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?

The description is two concise sentences with the primary action front-loaded. Every sentence adds value: the first states the scope and output fields, the second states the intended use.

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 zero-parameter, read-only list operation, the description is complete. It names the resource, scope, output content, and use case. No output schema exists, but the description supplies the essential return-value expectations.

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 there is nothing to clarify about inputs. The description still helps by describing what the returned namespace information includes, which is sufficient given the empty input 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 and resource: 'List all well-known OPC UA companion spec namespace aliases' with their names, URIs, and dependencies. It clearly distinguishes this tool from siblings like list_types and search_types by focusing on companion spec namespaces.

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 explicitly says 'Use this to discover what namespaces are available,' giving a clear intended use case. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough for a zero-parameter discovery tool.

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 convey readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that the tool enumerates all relevant type definitions exhaustively and frames itself as a required discovery step. There is no contradiction with annotations, but the description does not disclose additional behavioral details such as output shape or error conditions.

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 terse sentences carry both the tool's scope and its primary usage rule. The information is front-loaded, with no filler or 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?

For a single-parameter listing tool with no output schema and simple annotations, the description is largely sufficient. It tells the agent what it lists and when to call it. A minor gap is that it does not mention how to discover valid aliases, e.g., by first calling list_namespaces, though sibling context partially compensates.

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%, with the alias parameter already documented as a companion spec alias with examples. The description's reference to a 'specific companion spec namespace' aligns with the schema but adds no new semantic detail beyond what the schema provides, so 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 names a specific action ('List') and a precise resource: 'ALL ObjectTypes, VariableTypes, and InterfaceTypes defined in a specific companion spec namespace.' This clearly distinguishes the tool from generic listing or searching tools by emphasizing namespace-scoped enumeration of all three type categories.

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 an explicit condition for use: 'ALWAYS call this before using any type from a namespace — NEVER guess type names.' It does not, however, mention when not to use it or point to alternatives like search_types or get_type_details, so it stops short of full usage differentiation.

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 annotations, the description adds meaningful behavior: AI auto-detects companion specs, produces documentation, validates, and auto-corrects errors. It also surfaces the API-key requirement. It does not contradict readOnlyHint or openWorldHint.

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 sentences and about 40 words, with the main purpose up front, then the prerequisite, then behavior. Every sentence adds information; there is no filler.

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 the simple two-parameter schema, read-only annotation, and no output schema, the description provides enough context for selection and intent. It does not specify the exact return shape or failure modes, but the output type (YAML model) is clear.

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 covers both parameters with descriptions, so the 100% schema coverage sets the baseline. The description adds no parameter-specific meaning beyond reinforcing that prompt is the natural-language input.

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 action (generate), a precise output (OPC UA YAML model), an input source (natural language description), and a method (using AI). This distinguishes it from sibling operations like validate and reverse, even though opcua_model_generate is a close sibling.

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 clearly implies when to use it: when an OPC UA model should be produced from an NL description, and it gives a hard prerequisite (OPCUA_MODELER_API_KEY). It does not explicitly name alternatives or exclusion cases, which keeps it below 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 the operation read-only and idempotent; the description adds that an API key is required, outputs are base64-encoded, invalid models return diagnostics, and include_docs incurs a slower execution. This goes beyond the structured annotations without contradicting them.

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 sentences with the core purpose front-loaded. Each sentence covers a distinct aspect: action, prerequisites/returns, and optional behavior, with no wasted words.

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 two-parameter tool with rich annotations and no output schema, the description is sufficient: it names required auth, return format, error behavior, and the optional flag. An agent has enough information to invoke 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?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description mentions 'from a YAML model' and optionally re-states include_docs=true, but it does not add new meaning beyond what the input schema provides.

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: it generates OPC UA NodeSet2.xml and Symbols.CSV from a YAML model. This clearly distinguishes it from sibling tools like validate or reverse by naming both the input and the output artifacts.

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 phrase 'from a YAML model' and the output artifacts establish a clear use case: producing NodeSet2 artifacts from a YAML source. It does not explicitly name alternatives or provide when-not-to-use conditions, but the context is clear and it includes an important prerequisite (API key).

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 discloses an auth requirement not present in annotations: 'Requires an API key (set OPCUA_MODELER_API_KEY env var).' It also clarifies extraction behavior via the optional namespace URI. Since annotations already cover read-only/idempotent/open-world traits, the description adds valuable context beyond them.

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 tight sentences, front-loading the core purpose first. The second sentence combines the auth requirement and optional parameter without wasted words or redundancy.

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 covers the tool's purpose, input format, output format ('YAML DSL format'), auth prerequisite, and optional namespace filtering. With both parameters documented in the schema and read-only/idempotent annotations supplied, nothing essential for calling this tool 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 description coverage is 100%, so the baseline is 3. The description adds minor meaning by identifying the input as NodeSet2.xml content and mentioning the namespace URI as an extraction target, but it largely restates what the schema already says.

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 and resource: 'Reverse-engineer a NodeSet2.xml file back into the YAML DSL format.' This clearly conveys the tool's core purpose and likely distinguishes it from siblings like opcua_model_generate, though it does not explicitly name alternatives.

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 the tool should be used when converting NodeSet2 XML to YAML DSL and notes the API key prerequisite. However, it does not explicitly state when to prefer this over sibling tools like opcua_model_generate or opcua_model_create.

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 declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds valuable behavioral context beyond them: the exact diagnostic output shape (severity, codes, messages, line numbers) and the API-key-free rate limit. This fully covers what an agent needs to know about the call's behavior.

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 concise sentences, each with purpose: what it does, what it returns, and when to use it. 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?

For a single-parameter validation tool with no output schema, the description adequately compensates by explaining the return structure (errors/warnings/info, codes, messages, line numbers) and the mandatory usage order relative to generation. An agent has enough context to invoke 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 schema already documents the single 'yaml' parameter at 100% coverage ('The full YAML model source to validate'). The description adds no new parameter semantics, but none are needed; 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?

States a specific verb (validate), resource (OPC UA YAML model), and purpose (correctness), and clearly distinguishes from sibling generation/reversal tools. The 'ALWAYS validate before generating' instruction further clarifies its role in the workflow.

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?

Explicitly instructs when to use the tool ('ALWAYS validate before generating'), and provides operational context (works without an API key, 50 calls/day limit). This gives an agent clear selection and ordering guidance relative to generation siblings.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that it produces a 'full resolved dependency list' and is a prerequisite step, but provides no details on return format, ordering, or failure behavior. This is adequate but not rich.

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 filler. The core behavior is stated first, and the workflow directive is front-loaded and directly actionable. Every clause 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 clear annotations, the description covers the essential inputs, the output concept, and the workflow context. The absence of an output schema is mitigated by the statement that the result is a 'full resolved dependency list' for the YAML namespaces section.

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% and the schema already documents aliases as 'Companion spec aliases to resolve' with an example. The description's 'one or more' adds slight cardinality emphasis, but it mostly restates what the schema provides, so 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 uses a specific verb ('resolve'), a clear resource ('namespace dependencies'), and ties the result to a concrete artifact ('YAML namespaces: section'). This distinguishes it from siblings like list_namespaces by focusing on dependency resolution rather than mere listing.

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 explicit instruction 'Always call this before generating the namespaces block' tells the agent when to use the tool in the workflow. It does not mention alternatives or when not to use it, but the stated context is sufficient for correct sequencing.

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 signal readOnly and idempotent behavior, and the description adds the important cross-spec search scope plus the fact that results include the namespace alias for disambiguation. It does not describe match semantics like case-sensitivity or substring matching, but this is minor for a read-only search.

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 short sentences, each carrying distinct information: the action, the trigger condition, and the return shape. There is no filler or redundancy.

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 one required parameter, no output schema, and annotations covering safety, the description is sufficient: it states scope, expected output, and when to use it. Nothing is missing that would prevent a correct invocation.

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 query parameter is fully described in the schema, including example keywords, so the schema does the heavy lifting. The description adds little beyond calling it a keyword, which is already present 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 names a specific action ('search for types') and a defined scope ('across ALL companion specs'), which clearly differentiates it from siblings like list_types or get_type_details. The immediate usage condition ('when you don't know which namespace defines a type') further pins down its role.

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?

Explicitly states the trigger condition: use this when the namespace is unknown. It stops short of naming sibling alternatives or stating when not to use it, such as when the namespace is already known, which prevents a perfect score.

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