PLCGateway support

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the shape of the returned page (driver, connection settings, address syntax with examples, readable values, tips, FAQ) and the no-match behavior, which is exactly what an agent needs to decide whether the call answers its question.

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 purpose and return contents are front-loaded, the examples and fallback each earn their place. The first sentence is a long run-on that stacks several enumerations, which slightly reduces scanability.

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?

There is no output schema, so the description correctly takes on the burden of describing the returned content, and it does so concretely. The only gap is the language parameter's fallback behavior when a language is unavailable, which is only hinted at by the schema wording.

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 both the query string and the language enum are already documented in the schema. The description's example values illustrate acceptable query forms but add no rules about matching, normalization or what to do when a query is ambiguous.

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 ("Checks whether a PLC, CNC, controller family, model, brand or protocol is supported") and immediately broadens the accepted input space with concrete examples. It is clearly distinguishable from siblings like price_quote, product_info and search_docs, which do not describe support 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?

Usage context is clear: call this when you need to know whether a device or protocol is supported, and the sample queries ("S7-1200", "Modbus RTU", "IEC 104") show the expected granularity. The no-match fallback ("it lists the supported protocols") gives useful recovery guidance. It stops short of explicitly saying when to prefer search_docs or product_info 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is low. The description still adds real business context the annotations cannot: pricing is list price, EUR, excluding VAT, licences are perpetual and one-per-computer with all drivers and no device/tag limits, and the first year of updates is included. It does not say whether the response is itemized or what fields come back, which matters since there is no output 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?

Front-loaded with the core definition, then constraints, then the escalation path — dense and mostly waste-free. A few phrasings are compressed to the point of ambiguity ('offer request_demo then'), costing a little clarity.

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 5-parameter read-only pricing tool with no output schema, the description covers scope, pricing rules, exclusions and the alternative tool. What is missing is a sense of the returned shape (itemized breakdown vs. single total) and how module pricing combines, which an agent might need to interpret results.

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 60% and the description compensates meaningfully: it constrains 'modules' to specific product contexts, ties 'computers' to one licence each, and clarifies 'maintenance_years' as years bought after the included first year. The modules wording ('SCADA and Embedded only') is somewhat opaque against enum values quality_maintenance/energy and could confuse an agent, but the added meaning clearly exceeds 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?

States a precise verb and resource ('Calculates the list price of PLCGateway licences') plus the currency (EUR) and VAT treatment, which are the defining attributes of a quote. An agent can easily tell this apart from product_info (information lookup) and request_demo (commercial follow-up).

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 names the exclusion case and routes it to an alternative: 'Embedded and Enterprise are priced on request: offer request_demo then.' That is a clear when-not plus alternative. The remaining gap is no guidance on when to prefer this over product_info for descriptive vs. price questions.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: content is sourced from the official website, and it proactively discloses a limitation ("references ... names not published"), which tells the agent not to push for customer names. It does not describe response shape or length, but that is a minor omission for a read-only 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 purpose statement is correctly front-loaded, but the topic enumeration is one very long run-on sentence packed with parentheticals, which is dense to scan and mixes high-value routing info with marketing phrasing. Each parenthetical roughly earns its place by mapping to an enum value, so it is not padding, but a list or line-broken structure would be far more usable.

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, closed-world, read-only lookup with no output schema, the description supplies everything needed to invoke it correctly: the semantics of every topic value and the source of the content. The only real gap is routing guidance relative to price_quote, device_support and search_docs, which the description never mentions.

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 only 50% — the topic enum has no per-value descriptions in the schema — but the description compensates by glossing every one of the 15 enum values (e.g. "scada (screens, alarms, history, reports, OEE)", "kepserverex_migration (moving tags from KEPServerEX)"). That is meaningful added meaning an agent needs to pick the right topic. The language parameter's semantics come entirely from the schema, not the description.

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?

"Explains what a PLCGateway product, module or topic is for, who it is for, what it includes and how it works, from the official website" gives a specific verb (explains), a resource (product/module/topic), and a source (official website). The enumerated topic list further pins down scope. It stops short of distinguishing itself from siblings like search_docs or price_quote, which overlap with the pricing and protocol topics.

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?

Usage is only implied: an agent can infer this is the conceptual/marketing overview tool because every topic is a product-explanation category. There is no explicit when-to-use or when-not-to-use statement, and no guidance on choosing between this tool and price_quote (for pricing) or search_docs (for protocol detail), which are real potential confusions given the topic list.

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, it discloses the external e-mail side effect, direct follow-up by the team, the consent gate, and the prohibition on inventing or reusing contact details. It also limits how the details will be used and supplies a privacy notice, all consistent with openWorldHint=true and readOnlyHint=false.

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 purpose and side effect are front-loaded, followed logically by data collection, anti-fabrication, confirmation, and privacy rules. Although dense, every sentence serves a distinct invocation or safety purpose and 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?

For an eight-parameter tool with an externally visible effect and no output schema, the definition covers the recipient, side effect, required and optional inputs, consent requirements, privacy, and follow-up behavior. Together with the schema's constraints and annotations, it leaves no material gap likely to cause an unsafe or incorrect 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?

With only 38% schema description coverage, the description compensates by identifying name and e-mail as required, explaining the optional company, phone, product, and machine/goal details, and reinforcing the confirmation semantics. The schema covers the remaining language behavior, enums, defaults, and field constraints, so the combined definition gives practical meaning to all 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?

The opening sentence specifies the action, request types, recipient, and channel: sending a demo, trial, or offer request to the PLCGateway team by e-mail. It does not explicitly distinguish an offer request from the sibling price_quote tool, leaving a small selection ambiguity.

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 invocation workflow: collect the user's details, show exactly what will be sent, obtain explicit permission, and only then set user_confirmed to true. It gives no explicit when-not-to-use guidance or alternative tool for pricing-only or informational requests.

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, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is covered; the description adds real context on top by disclosing the return content (URL plus summary) and the fact that it searches the whole site rather than a subset. It stops short of stating how many matches are returned, whether results are ranked, or any truncation behavior, which are the remaining behavioral unknowns for a search tool.

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, zero filler. The scope and result shape come first and the follow-up routing second, which matches the order an agent needs the 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?

For a two-parameter, non-destructive search tool with no output schema, the definition covers scope, result shape, and the next step, which is close to everything an agent needs to invoke it correctly. The only meaningful omission is result-count/pagination behavior and any hint about query construction, both minor for a simple site search.

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 50%: the 'language' parameter carries its own description and enum, while 'query' has only type and length constraints. The description adds no syntax or format guidance for the query (keywords vs. natural language, whether product names work better), so it neither compensates for the gap nor misleads; baseline 3 applies.

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 ('Searches') plus a concrete, bounded resource ('all pages of plcgateway.com') and even enumerates the content types covered (products, modules, protocols, controllers, guides). It also states the shape of the result ('best matching pages with URL and summary'), which lets an agent distinguish this discovery tool from the sibling lookup tools without opening any 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 routes the agent onward: 'Follow up with product_info or device_support for the full text,' which tells the agent that this tool returns snippets and that sibling tools supply detail. What it does not cover is when NOT to search (e.g., a direct product lookup or price_quote/request_demo case), so the alternative set is only partially addressed.

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