Siemens

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

Annotations already establish readOnly, idempotent, openWorld, non-destructive, so the safety burden is light. The description still adds real behavioral detail: the AI answer is generated only on the first page, results are title/url/short description, and a follow-up call to siemens_get_web_content with a url is needed to read the full page. It stops short of covering paging limits or cost/latency implications, keeping it at 4 rather than 5.

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 tight sentences: capability first, then usage condition, then exclusions, then return shape and next step. Every sentence carries distinct information and nothing is restated from 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 7-parameter, read-only search tool with a full output schema, the description covers scope, selection, exclusions, return fields, and the follow-up call. An agent has everything needed to invoke it correctly and chain it with siemens_get_web_content.

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 and the schema already documents query, offset, region, language, maxResults, summaryLevel, and response_format thoroughly. The description adds only the paging loop hint (offset/next_offset) and the url pass-through to siemens_get_web_content, which is useful but well within what the schema already conveys.

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: 'Pages through siemens.com web content' and enumerates the content types (articles, solution pages, press releases, case studies). It also carves out the negative space against siblings (no products, no images/videos), so an agent can tell it apart from siemens_search, siemens_productSearch, and siemens_assets without opening a 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?

Explicit selection criteria are given: use when siemens_search returned too few pages, when page 2+ is needed via offset/next_offset, or when only content pages are wanted. Explicit exclusions route to siemens_productSearch and siemens_assets by name, which is exactly the when-not/alternative guidance that makes sibling selection reliable.

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, so the bar is low, yet the description adds genuinely new obligations: results carry usage-rights levels, approval requirements, a required credit line, previews and multi-size download URLs, and it imposes a policy duty ('Always tell the user the usage rights and credit before they reuse an asset'). That is behavioral context an agent could not infer from the 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?

Sentences are front-loaded in a logical order: purpose, result shape, usage-rights duty, filter tip, exclusions. It is on the long side and the illustrative list ('for a presentation, article or web page') is mildly expendable, but nothing else is padding.

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 9-parameter, multi-enum search tool with an output schema, the description covers what it searches, how to cite results, how to filter, and where to go instead. Return values are described at a level useful for downstream answering without duplicating the output schema's field-level detail.

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; the description nevertheless adds cross-parameter guidance by telling the agent to set usageRights to "UNLIMITED" for external or third-party use, which links a filter value to a real-world decision. It does not add meaning for the other eight parameters, so it stops short of a 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?

States a specific verb and resource ('Finds publicly released Siemens media in the Web Asset Pool') and immediately enumerates the asset kinds (photos, videos, PDFs, audio, icons). It also explicitly distinguishes itself from the sibling text tools siemens_search and siemens_developer_search, so an agent can route 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?

Gives concrete when-to-use triggers ('needs a picture, video, logo, icon or downloadable document... for a presentation, article or web page') and explicit when-not-to-use routing to siemens_search for text answers and siemens_developer_search for developer docs. It even prescribes a selection rule for the usageRights filter when the asset is for external use.

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 read-only, open-world, idempotent annotations, it discloses the searched corpus and explains that results are best-matching documentation sections containing a URL and snippet rather than complete pages. The companion-tool handoff clarifies the retrieval workflow, although operational details such as ranking or freshness are not discussed.

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 dense but efficient, front-loading the purpose and searchable content before covering use cases, result behavior, and exclusions. Each sentence supports tool selection or invocation, and the examples are brief and relevant.

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?

Together with the rich input schema, output schema, and safety annotations, the description provides everything needed to select and invoke the tool correctly. It covers scope, appropriate and inappropriate queries, result granularity, and the next step for retrieving complete documentation.

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 fully documents all six parameters, including paging, product filtering, defaults, and response verbosity. The description adds useful natural-language query examples and product-scope context beyond those field definitions, but most detailed parameter semantics remain 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 uses a specific verb and resource, identifying searches of the Siemens Developer Portal and enumerating the documentation types and platforms covered. It clearly distinguishes this technical-documentation search from general Siemens search and from full-page retrieval.

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 to use the tool for technical questions about Siemens APIs and developer tools, with concrete example queries. It also gives an exclusion for marketing, company, and product-catalog questions, routes those to siemens_search, and directs full-page reads to siemens_get_web_content.

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 read-only, idempotent, non-destructive, open-world behavior, yet the description adds substantial context beyond them: chunked returns with a next_offset continuation protocol, automatic JavaScript rendering with a slower (~20 s) forced-render path, an "extraction" field indicating which path was used, and domain rejection. These are exactly the operational traits an agent needs and none are in 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?

Front-loaded with purpose and scope, then usage routing, then pagination and rendering behavior, then exclusions. Dense and mostly earned, though it is a single long block and the rendering/extraction detail could be trimmed slightly for readability.

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 four-parameter read tool with an output schema, the description covers everything needed to call it correctly: where it applies, how to continue a long page, how rendering is chosen, and how the result is shaped. Return values are handled by the output schema, so no further detail is required.

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 adds cross-parameter meaning the schema does not: it explains that continuation requires reusing the same url with offset set to next_offset, and that `render` defaults to automatic unless the plain fetch yields almost no text. It adds little about maxLength beyond what the schema 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?

States a specific verb and resource ("fetches one public page on siemens.com... returns its main content as clean markdown") and bounds it to three Siemens domains plus developer.siemens.com. This is clearly distinguishable from the search siblings, which the description names explicitly.

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 positive triggers (after siemens_search, siemens_productSearch or siemens_developer_search, or when the user supplies a Siemens URL) and explicit exclusions (not for searching - use siemens_search - and not for non-Siemens sites, which are rejected). Nothing is left 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful context beyond them: the return shape (title, url, short description) and the pagination mechanism (offset/next_offset) for continuing across calls. It omits caps or rate limits, but the schema's maxResults bound of 30 covers the practical limit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences: purpose and scope first, then usage routing, then exclusions, then return/paging behavior. There is no repetition of the tool name or title, and no sentence could be removed without losing information the agent needs.

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 six-parameter read-only search with a full output schema, the description covers purpose, alternates, exclusions, return fields, and paging. It need not enumerate return values in depth because the output schema carries them, and nothing needed to call 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 every parameter (query examples, offset/next_offset paging, region, language, maxResults, response_format) is already documented in structured fields. The description's only added semantic is tying paging to the previous response's next_offset, which largely restates the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

"Pages through the Siemens product catalog (hardware, software and services such as SIMATIC, SINAMICS, Teamcenter, Xcelerator) for a query" gives a specific verb, resource, and scope, with concrete content examples. The agent can distinguish this catalog-paging tool from siemens_search and siemens_get_web_content 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?

Explicit when-to-use (specific products, families, order numbers, or needing more results than siemens_search returned) and explicit when-not-to-use (general explanations/news → siemens_search; single-product datasheets → siemens_get_web_content). Every sibling alternative an agent could confuse it with is named with the condition that selects it.

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, openWorld and non-destructive, so the safety profile is covered. The description adds behavior annotations cannot express: the single call runs three searches in parallel, returns an AI answer plus pages plus catalog products, is scoped to public siemens.com content only, and requires citing returned URLs rather than inventing links.

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 purpose, then fan-out behavior, then routing, then exclusions, then the citation rule — a deliberate most-to-least-important ordering. Every clause carries routing or behavioral information; there is no restatement of the tool title or 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 a five-parameter, open-world search tool with an output schema, the description covers everything an agent needs: what it returns, when to prefer it, where to page next, what to avoid, and how to cite. Return-value details are correctly left to the output schema rather than duplicated.

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%, including worked examples for query, region, language, the 60/40 page/product split for maxResults, and enum guidance for response_format, so the description is not required to carry parameter meaning. The top-level text adds no parameter detail beyond what the schema already states, making the baseline 3 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?

Opens with a specific verb-resource-scope statement ("Default tool for any question about Siemens... on siemens.com") and immediately explains that one call fans out into three parallel searches. An agent can distinguish this from siemens_aiSearch, siemens_productSearch, and siemens_assets without reading 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?

Gives explicit ordering ("Use it first"), names each alternative and the exact condition that selects it (aiSearch/productSearch for paging, get_web_content for full-page reads), and states two exclusions with the correct fallback tools (images/videos/logos → siemens_assets, API/SDK docs → siemens_developer_search). Nothing about routing is left to inference.

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