aras-plm-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have highly distinct purposes, with clear separation between querying, lifecycle, BOM, workflow, identity, and admin operations. There is some near-overlap in pairs like release_item vs promote_item and advance_change vs vote_activity, but the detailed descriptions are strong enough for an agent to disambiguate.
Naming Consistency4/5
The naming is overwhelmingly consistent: aras_ + snake_case verb_noun patterns such as get_, create_, list_, and update_. A few deviations like aras_how_to and aras_new_revision break the verb-first pattern slightly, so it is not a perfect 5.
Tool Count1/5
With 71 tools, this is far beyond the typical well-scoped MCP server surface and into the extreme range. While the domain is complex, the massive number of specialized one-off helpers creates a serious selection and cognitive load for agents.
Completeness5/5
The tool set covers the full PLM lifecycle: query, create, update, delete, revisions, lifecycle, workflow, BOM, changes, documents, files, users, permissions, reports, AML, and administrative metadata. The only gaps, such as vault file upload, are explicitly documented as external limitations rather than avoidable omissions.
Average 3.7/5 across 69 of 71 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 7 commits in the last 12 weeks
- Last stable release on August 22, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the basic action of creating and linking, but doesn't disclose side effects, permission requirements, reversibility, or any behavioral traits that could affect usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise. However, it's concise to the point of being under-specified, lacking crucial operational details that would justify its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 7 parameters and no annotations or output schema, the description is far too minimal. It doesn't explain return values, prerequisites, or the behavior when optional parameters like perPart are omitted. Critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, so the description should compensate for the many undocumented parameters. It doesn't. It indirectly touches on the 'tipo' field by mentioning Document/CAD but provides no explanation for other parameters like name, item_number, authoring_tool, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a Document or CAD and links it to a Part, using a specific verb and resource. It distinguishes the action from generic item creation or relationship creation, though it doesn't 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus other creation tools like aras_create_item or aras_create_part. The description only says what it does, not when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It mentions that roles are needed for lifecycle transitions, which is useful context, but it does not disclose side effects (e.g., whether creating an identity has permission implications), whether the operation is reversible, or what happens if the parent group does not exist. There is no mention of required authentication or potential errors. The description is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, fairly concise and not bloated. The key purpose is front-loaded, followed by a note on lifecycle roles. The information about lifecycle transitions is relevant but slightly tangential, yet it doesn't harm conciseness. It could be trimmed, but it's near optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a creation tool with no output schema and no annotations. The description provides only basic creation semantics and a note on lifecycle roles. It lacks critical information for correct invocation: prerequisites (e.g., does the parent group need to exist?), naming rules, expected behavior on duplicate names, or permissions required. Given the complexity of identity creation in a system like Aras, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, meaning 'gruppoPadre' has a description but 'nome' and 'descrizione' do not. The description adds some context for 'gruppoPadre' (nesting) and explains the 'nome' is the identity name, but it does not elaborate on 'descrizione' or provide format constraints for 'nome'. Given the low coverage, the description does not sufficiently compensate; an agent might not know if 'nome' has specific naming rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Crea') and the resource ('gruppo o ruolo (Identity)'), and mentions optional nesting in a parent group. It differentiates from similar tools like aras_create_user and aras_create_item by specifying it creates identities, though it doesn't explicitly name a sibling. The purpose is clear and distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context about roles being used for lifecycle transitions, which hints at when to use this tool. However, it does not explicitly state when to use it versus alternatives like aras_create_user or aras_create_item, nor does it mention any exclusions or specific scenarios (e.g., 'use aras_create_user for user accounts'). The context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves an item, implying a read operation, but doesn't disclose any behavioral traits like whether it returns the full item or only specified properties, error handling, or performance characteristics. The description is minimal and doesn't add context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. It front-loads the core purpose. No wasted words, but it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, 2 required, and no output schema, the description is incomplete. It doesn't explain what 'itemType' is, how 'select' works, or what the return value looks like. An agent would need to infer or guess about the 'select' parameter and the response format. The description is too thin for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'id' has a description). The description mentions the 'id' parameter (GUID) but doesn't explain 'itemType' or 'select'. The 'select' parameter is an array that likely controls which properties to return, but this is not explained. The description adds minimal value beyond the schema, and the schema itself is sparse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single item by its Aras ID (32-character GUID). It specifies the verb (recupera), resource (elemento), and the key identifier. It doesn't explicitly differentiate from siblings like aras_get_aml or aras_query_items, but the focus on a single item by ID is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that this is for fetching a single item by ID, while aras_query_items or aras_search might be for broader queries. No exclusions or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as whether this is a read-only operation, whether it returns all saved searches or only the current user's, or any performance implications. The description is minimal and does not add behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise. It is front-loaded with the resource name. However, it is so brief that it borders on under-specification, but for a 0-parameter tool, it is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description should at least clarify what the tool returns and how it differs from similar list tools. The description is too thin to be considered complete; an agent might not know if this returns a list of names, full criteria, or how to use the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and schema description coverage is 100% (vacuously, since there are no properties). The description adds a bit of context by mentioning 'criteria' which might be part of the return value, but since there are no parameters, the description does not need to explain parameter semantics. Baseline 4 for 0 params is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Ricerche salvate dagli utenti, con i criteri che usano' (Saved searches from users, with the criteria they use) states the resource (saved searches) and implies a listing action, but the verb is implicit. It distinguishes from siblings like aras_list_reports and aras_list_queries by mentioning 'saved searches' and 'criteria', but the purpose is not fully explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like aras_list_queries or aras_search. The description does not mention any context, prerequisites, or exclusions. An agent would have to infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a mutation of an existing ItemType, but it gives no details on side effects, required permissions, whether the operation is reversible, what happens if the property already exists, or what the tool returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler or repetition. It is concise, but because it omits substantive guidance for several parameters it is not maximally useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no annotations, no output schema, and low schema description coverage, the description is too incomplete. An agent would know that the tool adds a property, but not enough about correct parameter usage, valid values, constraints, or expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the tool description does not explain any parameters. The existing schema descriptions cover 'tipo' and 'lunghezza' partially, but 'nome', 'itemType', 'etichetta', and 'obbligatoria' are not semantically explained anywhere. The description does not compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Aggiunge'), a specific resource ('una proprieta'), and a clear target ('ItemType esistente'). It is distinguishable from the many sibling tools, though it does not explicitly contrast itself with aras_create_item_type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a un ItemType esistente' implies the tool is for modifying an existing item type, not creating one. However, it gives no explicit guidance on when to choose this tool over alternatives, nor any exclusion or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden of behavioral disclosure. It only says 'adds an item' but does not explain side effects, whether it creates a relationship, what happens if the item is already affected, permission requirements, or the return value. The mutation is implied by 'Aggiunge' but the behavioral context is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the action and the target immediately. There is no wasted wording, so it earns full marks for conciseness even though more detail would be useful elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% schema description coverage, this one-sentence description leaves significant gaps. An agent does not learn how to supply the item, what itemType means, whether any preconditions exist, or what the operation returns. It is too incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter documentation. It indirectly hints at 'tipo' and 'changeId' via 'ECR/ECN esistente', but it says nothing about 'itemNumber' or the defaulted 'itemType' parameter. This is insufficient for a 4-parameter tool with no schema-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Aggiunge') and a clear resource ('un elemento fra quelli impattati da una ECR/ECN esistente'), so an agent can tell it adds an affected item to an existing change. It does not explicitly name sibling alternatives, but 'esistente' distinguishes it from change-creation tools. A solid, specific purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'ECR/ECN esistente' implies this tool is for existing changes, not for creating them, so usage context is somewhat clear. However, it does not explicitly contrast with alternatives like aras_create_relationship or aras_create_change, nor does it state when not to use it. This is implied rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies an export/read operation but does not disclose whether the result is returned as a string or file, whether relationships are included, or what limits apply. The mention of 'conservare uno stato' hints at snapshot behavior but does not explain observable effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler, and the core action is front-loaded. The use-case clause earns its place, though more structured detail could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, no output schema, and no annotations, this description is not complete enough. An agent would not know how to supply the required itemType, what massimo and conRelazioni control, or what the export returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate for the undocumented itemType, massimo, and conRelazioni parameters. It does not add any parameter-level meaning; 'elementi' is too vague to explain what itemType should contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Esporta elementi in AML', and adds the native-exchange-format context. It is distinguishable from the import sibling, though it does not explicitly contrast itself with aras_get_aml.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use context: transferring configurations between Aras instances or preserving state. It does not mention exclusions or alternatives explicitly, but the stated scenarios are enough to indicate when this export tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does reveal a significant non-obvious side effect: granting read ('lettura') automatically grants discover ('scoprire') because otherwise the item won't appear in searches. However, it does not disclose whether rights are added or replaced, whether the operation can revoke, or any authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states the core function, the second delivers a high-value behavioral caveat. The most important operational nuance is front-loaded and compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a permission-mutation tool with six parameters, no output schema, and no annotations, the description is too thin. It explains only one parameter interaction and omits semantics for the remaining flags, the mutation model (additive vs. replace), and expected return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter explanations. It only clarifies the relationship between 'scoprire' and 'leggere'; the other four parameters (nomePermesso, identita, cancellare, modificare) rely on their Italian names for meaning, which is not sufficient for a 6-parameter mutation tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Concede o modifica' = grants or modifies) on a specific resource ('Permission') for an identity, which clearly distinguishes it from read-only siblings like aras_get_permission_detail. However, it does not explicitly name alternative tools or scope conditions, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as aras_get_permission_detail or aras_manage_membership. The behavioral note about 'scoprire' is informative but does not help an agent decide when to invoke this tool over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses two behavioral aspects: property validation against the real schema before submission, and that the tool is disabled when the server is in read-only mode (ARAS_READONLY). This gives some insight into internal checks and a conditional disability, but it does not describe the return value, error handling, or any side effects beyond creation. The disclosure is partial but useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences. The main action is front-loaded, and the additional details about validation and read-only mode are given efficiently. There is no unnecessary fluff, and the structure is clear and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides basic context about validation and a read-only constraint, but it omits crucial information such as what the response contains after a successful creation, error patterns, or examples of usage. Given the simplicity of the tool, a more complete description would mention the return value and typical success indicators. The lack of output schema amplifies this gap, making the description only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes dryRun and properties, but itemType lacks a description. The tool description does not add clarification for itemType or any further semantics for the other parameters. The validation mention relates to the properties parameter but does not elaborate on expected formats or constraints. With 67% schema coverage, the description fails to compensate for the missing itemType guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Crea un nuovo elemento' (Creates a new item). It specifies a concrete action (create) and resource (item), which distinguishes it from sibling tools like aras_update_item or aras_search. The intent is immediately clear without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as aras_create_part or aras_create_document. It does not mention typical use cases, prerequisites, or conditions that would lead an agent to choose this tool. The only additional info is a constraint about read-only mode, which is about disabled state, not usage selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys that the tool lists metrics and supports filtering by name, but does not disclose the return format/shape, whether the filter is exact or partial match, whether the full list is returned when no filter is given, or any pagination/volume behavior. For a list tool with zero annotation coverage, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy; the purpose is front-loaded with examples first, and the filter guidance follows. Efficient and appropriately sized for a single-parameter list tool, though the second sentence could add slightly more actionable detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter listing tool with no output schema and no annotations, the description covers the core purpose and filter behavior adequately. It is missing return/format details and filter matching rules, but these are relatively minor for such a simple retrieval operation, making the definition borderline-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented 'filtro' parameter. It does add meaning by specifying the filter applies to the metric name ('Filtra per nome'), which is value beyond the bare parameter label. However, it does not clarify matching semantics (substring vs. exact, case sensitivity), leaving partial compensation for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb (list) and resource (metrics and indicators defined in Aras), backed by concrete examples ('ECR Cycle Time', 'Cost vs. Goal', 'CAD Model Release Time') that distinguish these from reports or item types. It does not explicitly differentiate from sibling list tools like aras_list_reports or aras_list_dashboards, but the resource is specific enough to infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives usage guidance for the filter parameter ('Filtra per nome se ne cerchi una in particolare'), telling the agent to use it when looking for a specific metric. However, no explicit when-to-use/when-not-to-use guidance versus other list tools is provided, nor any exclusions, so the usage context is only implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself must convey side effects. It states that it creates and approves, but does not mention permissions required, whether it modifies existing data, implications for the part's lifecycle, or error behavior. The mention of 'creando il costruttore se non esiste' gives some behavior but is insufficient for a fully transparent contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey the core action and its multi-entity coverage. It is well-structured, front-loading the main verb and object, and avoids unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and moderate complexity (4 required parameters, multiple entities). The description covers the high-level action but omits return value expectations, failure conditions, and any post-conditions (e.g., status of the part after approval). Without this, an agent cannot fully anticipate the tool's behavior in a complete workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for only two of four parameters (mpn and perPart), and the description does not distinctly map each parameter. While it hints at 'costruttore' and 'descrizione', it does not clarify their exact roles (e.g., what 'descrizione' applies to). The description fails to compensate for the missing schema details, leaving ambiguity for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (adds a manufacturer part and approves it on a part) and the resource (Manufacturer Part, Part). It also specifies the conditional creation of the manufacturer, making the primary purpose unambiguous. It distinguishes itself from siblings by emphasizing the combined 'one step' coverage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for scenarios requiring simultaneous creation/approval and manufacturer handling, but it does not explicitly contrast with alternative tools (e.g., aras_create_part or aras_create_relationship). The 'Copre in un passo' phrase suggests a single-step convenience, but there is no explicit 'use this instead of X when' guidance, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It usefully reveals that revision, state, and audit data are regenerated by Aras, which is important context. However, it does not mention permissions, side effects on the original part, return values, or error behavior, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core action and optional BOM behavior, and the second adds the key regeneration detail. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for basic understanding but incomplete for a mutation tool with no annotations and no output schema. It lacks usage differentiation, return-value expectations, and error conditions, so an agent may still need to infer important invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the description must partially compensate. It adds meaning to conDistinta by explaining it as the first-level BOM, but it does not clarify nuovoNome or add format/syntax details for origine and nuovo beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool duplicates a Part with its domain properties and optionally the first-level BOM, using the specific verb 'Duplica' and resource 'Part'. It is clear and informative, but it does not explicitly differentiate from sibling tools like aras_create_part or aras_new_revision, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as aras_create_part or aras_new_revision. The phrase 'se richiesto' only indicates that copying the first-level BOM is optional, not when this tool should be preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states that it creates a model, with no mention of side effects, permissions, or response format. For a mutation tool, this is a significant gap—the agent has no indication of what happens beyond creation or whether any prerequisites exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It front-loads the purpose and includes a concrete example, which is efficient and easy to parse for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema and sparse annotations, the description is incomplete. It fails to explain the relationship between the model and effectivity beyond a brief mention, and does not describe input expectations or outcomes. An agent would struggle to know what to provide and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It does not mention 'nome' (name) or 'etichetta' (label) at all, leaving the agent without any understanding of their purpose or format. This is a critical omission for a tool with only two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: creating a product model, and provides a concrete use case (as the Model variable value for effectivity, with examples 'CP-40', 'CP-60'). This distinguishes it from other create tools (e.g., aras_create_item) by name and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: to create a model intended as an effectivity Model value. It implicitly differentiates from generic create tools, though it doesn't explicitly state when not to use it or mention alternatives. The example values add practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does add useful behavioral context: it combines two distinct relationships (Document and CAD) into one call. It does not disclose return format, read-only nature, or error behavior, but for a simple getter this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The main function is front-loaded in the first sentence, and the second sentence adds valuable context about the two Aras relationships.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool, the description covers the core purpose and scope. However, with no output schema, it does not explain what the response contains (e.g., metadata vs. file content) or any limitations, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, partId, with no description (0% coverage). The description only refers to 'una Part' and does not explain what partId should contain, its format, or how it is used. The description should compensate for the missing schema documentation but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all documentation for a Part, explicitly listing Documents (drawings, specifications, manuals) and CAD models in one call. It identifies the resource and scope, though it does not explicitly differentiate from sibling tools like aras_get_files or aras_get_relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in una sola chiamata' and the note that two distinct Aras relationships answer the same question imply this tool is for fetching both document and CAD data together. However, it does not state when to prefer alternatives or provide explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the InBasket analogy and prerequisite lookup, but doesn't disclose whether it includes closed activities by default, pagination/limits, authentication requirements, or what the return structure looks like. The parameter 'soloAperte' is not mentioned in the description, leaving default behavior unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose and a helpful prerequisite. The second sentence is actionable guidance. It could be slightly more structured but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks behavioral details (return format, default filtering, ordering) that an agent needs when no output schema is present. It gives a useful prerequisite but leaves key operational aspects unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mentions 'identityId' concept indirectly ('attivita' in carico a un'identita') and the prerequisite to find the id, but adds little beyond the schema. The 'soloAperte' parameter is not discussed in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool retrieves activities assigned to an identity (user or group) and explicitly equates it to Aras's InBasket, which distinguishes it from generic list tools. The verb 'Attivita' in carico' is specific, though it doesn't contrast with siblings like aras_get_my_identities or aras_query_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to first find the identity id with aras_query_items on 'Identity', giving clear usage context. It doesn't explicitly exclude alternatives or state when not to use it, but the prerequisite workflow is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It implies a read operation via the tool name and the phrase 'Diritti concessi', but it does not explicitly confirm read-only behavior, mention required authentication or permissions, describe the response format, or note any side effects. This is a significant gap for a tool with no structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and provides a concise list of what the tool returns. There is no fluff or unnecessary repetition, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately states what it returns (permission rights per identity). However, it omits details about the response structure, any required permissions to invoke the tool, or potential error conditions, which would be helpful given the lack of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter (nomePermesso) with 100% coverage, including an example. The description does not add meaningful extra context about the parameter value beyond what the schema provides, so it meets the baseline for adequate parameter documentation but adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the rights granted by a permission to various identities, including read, modify, delete, and discover operations. It is specific and not a tautology, but it does not explicitly distinguish it from sibling tools like aras_get_type_permissions, which also deal with permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining what information is provided (permission rights per identity), offering clear context. However, it does not mention when to choose this tool over alternatives or any conditions that favor its use, nor does it state exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It does reveal a key behavioral nuance — the conditional tense 'verrebbe assegnato' indicates the tool does NOT consume the sequence counter, which is valuable for a read-only listing tool. However, it doesn't disclose whether the listing reflects the caller's permissions, whether sequences can be filtered, or what fields accompany each sequence entry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence in Italian with no wasted words. The resource type is front-loaded, followed by concrete examples and the key behavioral detail. Minor deduction for omitting an explicit leading verb (e.g., 'Elenca...' / 'Lists...') and for the language mismatch between the English tool name and Italian description, though the latter may be intentional for end users.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameter-less read-only list tool with no output schema, the description is mostly adequate — it identifies the resource, gives examples, and clarifies the non-consuming nature of the read. However, it doesn't describe the structure of the return value (mapping? array of objects?), which would be helpful since there's no output schema to rely on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter documentation burden. The 0-param baseline is 4, and the description adds value by clarifying what each listed item contains (sequence identifier and its next value), partially compensating for the absence of an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific resource (configured automatic numbering sequences) with concrete examples (ECR, ECN, Part...) and a valuable differentiator — it shows the next value that would be assigned. The verb 'list' in the name plus the description's specificity make the purpose unambiguous, and the resource is distinct from sibling list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
With over 80 sibling tools, including similar list_* operations (aras_list_reports, aras_list_item_types, aras_list_dashboards), the description offers no guidance on when to prefer this tool over alternatives. There is no when-to-use, when-not-to-use, or mention of alternative tools for related needs like checking specific sequence assignments or counters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose that dryRun is default and lists without writing, implying that without dryRun it does write. However, it does not explicitly warn that updates are permanent, that a large number of items could be affected, or any authorization requirements. The mutating nature is implied but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences with no filler. It front-loads the main purpose and then highlights the dryRun default. No additional structure needed. It could be slightly expanded with key parameter notes, but it is appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk mutation operation with no annotations, no output schema, and only partial parameter coverage, the description is incomplete. It does not explain the return value, the constraints on massimo, the requirement for exact itemType, or the irreversible nature when dryRun is false. An agent would need to infer or inspect the schema further to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (2 out of 5 parameters have descriptions). The description adds value by explaining dryRun and the filter concept, but it does not mention itemType (essential for the operation) or massimo (the limit on number of items processed). For a bulk operation, these are critical, and the description fails to compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a bulk update of items matching an OData filter. The verb 'Aggiorna' (update), resource 'tutti gli elementi' (all items), and scope 'in blocco' (bulk) are explicit. This distinguishes it from sibling tools like aras_update_item which updates a single item, and from query tools that only read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives the default behavior of dryRun (listing without writing) but does not explicitly state when to use this tool versus alternatives. It implies the use case (bulk updates based on a filter) but omits exclusions, such as when to prefer single update or when the filter might be too broad. No alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose meaningful behavior: the tool validates the schema and list values, and it can optionally attach the part to a parent assembly. However, it leaves important operational details unclear, such as what actually happens on execution, whether dryRun prevents persistence, and what error or return behavior occurs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler. It front-loads the core action ('Crea una Part') and immediately follows with the distinctive behaviors that separate it from sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, only 1 required, a 36% schema description coverage, no annotations, and no output schema, this description is not complete enough. It does not explain required inputs, dryRun behavior, return values, permissions, or failure conditions, so an agent has to infer too much operational detail from parameter names and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds useful context for parameters involved in validation and BOM attachment, suggesting that list-valued parameters such as make_buy and unit are checked against existing values, and that parameters like sottoAssieme are intended for parent assembly linkage. That said, with only 36% schema description coverage, most of the 11 parameters still lack meaningful semantic explanation in both the schema and the description itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does in one combined verb: it creates a Part with validation constraints and optional BOM attachment to a parent assembly. This distinguishes it from generic creation tools such as aras_create_item and aras_create_document, so an agent can tell it apart without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose aras_create_part over aras_create_item, aras_create_document, or other creation tools. The usage context is only implied by the phrase 'Crea una Part', with no mention of exclusions, prerequisites, or conditions that should route the agent to a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It only describes the data contents (config details) but does not state that the operation is read-only, requires permissions, or has any side effects. The name implies a getter, but this is not explicitly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently lists the key aspects of the configuration. It avoids unnecessary words and is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a getter with no output schema, the description provides a reasonable list of what the configuration includes. It does not describe the response format, but this is not required given the absence of an output schema. The main aspects are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are no parameters to describe. The schema coverage is 100%, and the description adds no parameter-related details. Thus, the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (effectivity configuration) and lists the specific data it provides: scope, variables, defined product models, and expression counts on BOM lines. It is distinct from sibling tools, which focus on other Aras entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It is a getter, but there is no guidance on conditions or comparisons with other tools, such as when to use aras_get_effectivity_model or similar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It discloses that the operation mutates by adding/updating/removing, but does not explain the destructive nature of 'rimuovi', disambiguation when multiple lines might match, permissions, or what the result/error behavior looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact sentence with no filler. It leads with the action and concludes with the identifying mechanism, in a structure that is easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and three behaviors embedded in a single field, a one-line description is insufficient. It does not say how 'aggiorna' or 'rimuovi' targets a unique row, does not describe output/error response, and does not clarify whether editing is by (assieme, componente, riferimento) or by other criteria.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's reference to two Parts by item_number helps map to 'assieme' and 'componente' in the schema, and the listed verb 'aggiunge, aggiorna, rimuovi' directly mirrors the enum values for 'azione'. However, 'quantita' and the optionality/meaning of 'riferimento' are not explained further, leaving 60% schema coverage to carry most of the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: adding, updating, or removing a BOM line between two Parts. It also clarifies the key identification method (by item_number), which makes it distinguishable from sibling tools like aras_get_bom or aras_create_relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: this tool should be used when the agent needs to modify a BOM line. However, the description gives no explicit guidance on when not to use it or which sibling tool to prefer, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what is returned (users and sub-groups) but doesn't disclose whether it's a read-only operation, any authentication requirements, potential errors, or pagination. For a simple getter, the lack of such detail is a gap, though the tool's read-only nature is strongly implied by the name and 'get' verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded purpose. The second sentence is a pointer to a sibling tool, which is helpful. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and a clear read intent, the description explains what it returns and how to find the id. No output schema, so the description covers the essentials. Could mention output format, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverageión, the description must explain the single parameter identityId. It does mention using aras_query_items to find the id of the department, implying identityId is that idikuha. However, it says
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool returns members (users and sub-groups) of an Aras identity (department, group, role). The verb 'get' plus the resource is clear. It doesn't explicitly differentiate from sibling tools like aras_get_lifecycle_map or aras_search, but the purpose is specific enough to distinguish it from most siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the user how to obtain the required identity id via aras_query_items on 'Identity', which is a concrete usage prerequisite. It implies when to use this tool (when you have the id and want members) but doesn't explicitly state when NOT to use it or compare with alternatives. Still, it gives useful context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool lists report configurations and their associated ItemTypes, and gives examples of standard reports. However, it doesn't mention whether this is a read-only operation, any filtering capabilities, or what the output format looks like. The description is honest but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and front-loads the main purpose. The example list of standard reports adds value but is slightly verbose. Overall, it's efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool, the description is reasonably complete. It explains what is listed and gives examples. However, it doesn't mention whether the list is exhaustive, whether there are any filters, or what the output structure is. Given the simplicity of the tool, this is adequate but could be slightly more explicit about the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (vacuously, since there are no properties). The description adds context about what the tool returns (report configurations and their ItemTypes), which is useful since there are no parameters to document. With no parameters, the baseline is 4, and the description provides relevant context about the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool lists report configurations in Aras and mentions the ItemTypes they are attached to, with examples of standard reports. This is a clear verb+resource (list reports) and distinguishes it from siblings like aras_run_report and aras_list_item_types, though it doesn't explicitly name a sibling to differentiate from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for listing report configurations, which is distinct from running reports (aras_run_report) or listing item types (aras_list_item_types). However, it doesn't explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or context for when this would be needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the AML mechanism and the read-only limitation, implying a mutation. Yet it does not mention side effects, permission requirements, or return/error behavior, leaving the agent only partially informed about the operation'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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary purpose front-loaded, followed by a concise implementation note and a read-only warning. Every word earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and three parameters where two are undocumented, the description is incomplete. It lacks guidance on how to determine itemType and id, what the return value will be, and what error conditions may arise. The example and read-only warning help but do not fill the gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only toState is described). The description does not explain id or itemType at all; the example indirectly suggests itemType could be 'Part' and toState 'Released', but no explicit mapping or usage guidance is given. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Promuove un elemento a un nuovo stato del ciclo di vita') with a concrete example ('Part da Preliminary a Released'). This clearly distinguishes it from generic item operations and even from the sibling aras_release_item by emphasizing promotion to any state, not just release.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides contextual hints: it uses AML because OData does not expose transitions, and it is disabled in read-only mode. However, it does not explicitly contrast with alternatives like aras_release_item or state that aras_get_lifecycle_state should be used to obtain valid toState values; that hint appears only in the schema parameter description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the number is auto-generated by Aras and not to be provided, and that affected items must be created inline. However, it doesn't disclose other behavioral aspects like required permissions, whether the operation is reversible, or what the response contains. The description adds some value but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences that front-load the core purpose and then add critical usage constraints. Every sentence adds value, though the inline affected item note could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no output schema, no annotations), the description covers the key creation logic and the critical constraint about inline affected items. However, it lacks information about return values, error handling, or prerequisites like permissions. It's adequate but not complete for a tool that creates change objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33%, meaning most parameters lack descriptions. The description clarifies that 'tipo' selects ECR or ECN and that 'impattati' are affected items created inline. It also notes that 'proposed_solution' is only for ECR and 'implementation_plan' only for ECN, which adds meaning beyond the schema. However, it doesn't explain 'title' or 'description' beyond their names, and the schema already provides defaults and enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an ECR or ECN with its impacted items, using specific verbs and resources. It distinguishes from siblings like aras_create_item and aras_add_affected_item by focusing on the change object creation with inline affected items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: to create a change (ECR/ECN) with impacted items. It implicitly distinguishes from aras_add_affected_item by noting that affected items are created inline within the relationship, which is the only working method. However, it doesn't explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only says the activity is delegated rather than voted on and suggests how to find required IDs. It does not explain side effects of delegation, permission requirements, reversibility, or the role of the dryRun parameter, which is especially important given the default of true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, purposeful sentences with no filler. The primary action is front-loaded, and the lookup instruction is placed second. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter action with no annotations and no output schema, this description is incomplete. It omits the meaning of dryRun, the practical effect of delegation, and any expected return value. The get_workflow hint is useful, but not enough for an agent to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description partially compensates for low schema coverage by explaining that activity and assignment IDs come from aras_get_workflow, and that the target is another identity. However, dryRun and commenti are not semantically clarified, and with only 20% schema description coverage, this leaves meaningful gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delega'), a clear resource ('attivita' di workflow'), and the recipient ('a un'altra identita'). It also explicitly contrasts this with voting ('invece di votarla'), which distinguishes it from the sibling aras_vote_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by positioning the tool as an alternative to voting and instructs the agent to use aras_get_workflow to find the activity and assignment. It does not exhaustively enumerate when-not-to-use or all alternative tools, but it provides enough routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: validation against schema, generation of new revisions for versionable item types, and disabled in read-only mode. This goes beyond basic purpose and is very transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main action stated first followed by necessary warnings. It avoids unnecessary verbosity while including critical caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While it provides important behavioral warnings, it lacks explanations of parameters, expected output, and interaction with other tools. The absence of output schema and parameter details makes it incomplete for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the parameters (id, itemType, properties, dryRun). It only implies that properties is a set of updates, leaving the agent uncertain about parameter formats and meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates properties of an existing item, which is a specific and distinct action among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides some usage guidance (e.g., caution about creating new revisions on versionable types, check revisions if needed) but does not explicitly contrast with alternative update tools like bulk_update or promote_item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It states that the tool lists components not yet released, which is a concrete behavior. However, it does not mention whether the operation is read-only, what the return format is, or how to interpret the results (e.g., empty list vs. success). Given the absence of annotations, more behavioral detail would be expected for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two short, focused sentences. The primary purpose is front-loaded, and the second sentence adds a valuable warning. There is no wasteful phrasing or redundancy. It is exemplary in conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is moderately complex (with a depth parameter and a readiness check), and there is no output schema or annotations, the description is incomplete. It fails to explain what profondita means, what the response looks like (e.g., a list, boolean, or report), or any prerequisites. The agent cannot fully understand how to call it correctly or interpret results based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the tool description does not explain the parameters. While the context mentions 'assieme' (assembly) and 'distinta' (BOM), it does not explicitly map partId to the assembly or explain that profondita likely controls traversal depth. The agent must infer semantics from the schema types and defaults alone, which is insufficient. The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks whether an assembly is ready for release and enumerates the BOM components that are not yet released. It identifies the specific verb (check) and resource (assembly), and the action (list unreleased components). This distinguishes it from siblings like aras_release_item (which performs the release) and aras_get_bom (which retrieves the BOM without a readiness assessment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting that releasing a parent with children in Preliminary is the most common error, implying the tool should be used before a release to avoid this. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of fully explicit guidance. The implication is strong enough for an agent to infer the appropriate timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the main source of behavioral information. It discloses what the tool returns — approved Manufacturer Parts and their related manufacturer — which is useful. However, it never explicitly states that the operation is read-only, nor does it describe the response format or error behavior, though the 'get' verb in the tool name implies non-mutating access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the resource (approved manufacturers) and then states the purpose. Every word earns its place; there is no filler, redundancy, or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description covers the core elements: input subject (Part), output content, and intended use. However, with no output schema and no annotations, an agent is left to infer the exact response structure and identifier semantics. Adding an explicit statement like 'returns a list of approved manufacturer parts with manufacturer details for the given partId' would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `partId` appears in the schema just as a required string, with 0% schema description coverage. The description mentions 'per una Part' (for a Part), which hints that `partId` identifies the Part, but it does not specify whether it is an Aras Item ID, keyed name, or another identifier. The description partially compensates for the schema gap but leaves the identifier format unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: the Approved Manufacturer List for a Part, including approved Manufacturer Parts and the related manufacturer. It does not use an explicit verb like 'retrieves' or 'lists', but the content and scope are unambiguous and distinguish it from sibling tools. The name `get_aml` reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states explicit business contexts: purchasing and evaluating second sources. It does not name alternatives or conditions for choosing this tool over similar list tools like `aras_get_bom` or `aras_get_relationships`, but the intended use cases are clear enough for an agent to make a reasonable selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. It adds a key non-obvious behavior (history tied to config_id, covering entire life) but does not mention read-only nature, output format, pagination, or other operational details. The given information is useful but not comprehensive without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose. The technical detail about config_id follows logically, adding context without bloat. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description covers the core concept but leaves gaps: parameter details (especially what 'id' should be, and the meaning of 'limite') and expected response format are not addressed. Given low schema coverage, the description could do more, but it is not wholly inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only itemType has an example). The description does not explain the 'id' or 'limite' parameters, nor does it connect the config_id concept to the required 'id' parameter. With low coverage, the description should compensate, but it adds little parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource: provides an audit trail (who did what and when) across all revisions. It distinguishes itself from siblings like aras_get_revisions by explicitly noting the history is bound to the config_id, not a single generation, covering the entire object life.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides scoping context: explains that the history spans all revisions due to config_id binding, which helps the agent understand when to choose this tool over a revision-specific one. However, it does not explicitly name alternatives or state conditions for not using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given that no annotations are provided, the description carries the full burden — and it delivers by revealing the dual-source behavior (filesystem plus database) that the tool name alone would never divulge, as well as the configuration prerequisite for file logging. The fresh-install note ('possono essere entrambe vuote') preemptively explains surprising empty results. It still doesn't mention effects on the system, performance implications of includiDatabase, or whether it's read-only, but the disclosures are far above what generic prose would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences in Italian, front-loaded with the core purpose and reserving the second part for a genuinely decision-relevant edge case. No fluff, with the important scoping details (both sources, empty-on-fresh-install, configuration prerequisite) all present. A small nit: the architecture information could lose a few words, but it is already lean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The main complexity of this tool is its dual backend, and the description addresses it head-on, including the conditions under which each source may return nothing. Since there's no output schema, a brief note on how the two sources would be combined or formatted would make it more complete, but the description is already a strong package for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: righe and filtro have descriptions with ranges and an example regex, while includiDatabase is left undocumented. The description partially compensates by explaining the file-vs-database architecture that gives 'includiDatabase' meaning, effectively clarifying that it asks the request to consult the database source. However, it adds no parameter semantics beyond the schema — nothing about the regex flavor, how rows are read from the tail, or the meaning of the boolean default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The statement 'Log di Aras da due sorgenti' gives a specific verb and resource, further clarified by naming the two exact log sources (server files for 'Innovator, OAuth, Client' and the 'SystemEventLog' database ItemType), which exceeds a tautological restatement of the name. It accurately sets expectations that this tool reads logs from two heterogeneous backends. However, it doesn't position itself against obvious siblings like aras_read_file, so differentiation from similar read tools is left implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool applies by naming the exact sources it covers, and it surfaces a real usage pitfall: on fresh installs both sources may be empty and file logging must be enabled in server configuration. This is valuable caveat guidance for interpreting results correctly. It stops short of explicit when-to-use/when-not-to-use routing or side-by-side comparison with alternatives, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure — and it does disclose the most critical trait: the tool can execute destructive actions. The fact that the dryRun is described as reporting 'quante azioni distruttive contiene' before executing suggests a safety mechanism that an agent must be aware of. However, there's no mention of idempotency, atomicity, partial-failure behavior, or what the return payload looks like after a real apply — significant gaps for a state-mutating import tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense, well-ordered sentences carry a meaningful amount of information with no filler. The most important information (what it does, its relationship to a sibling) comes first, followed by the safety-related dryRun behavior. The only reason not to give a 5 is that the compactness comes at the cost of omitting the execution semantics entirely (what happens after a real apply), and the definition could easily make room for that with a couple more words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-blast-radius tool; it can apply AML packages that contain destructive actions — yet it has no annotations, no output schema, and no description of post-apply behavior. An agent won't know whether the import is transactional, what the response shape is, or whether it should expect the tool to commit changes beyond the dryRun. For the safety value of the dryRun feature to shine, the definition needs to either declare those semantics or point to a doc resource. The gap is noticeable compared to the export sibling, making this a missed opportunity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description does add meaning to the `dryRun` parameter: it explains that it's the default, that it analyzes the package, and reports the count of destructive actions before executing. This goes beyond the schema's 'boolean, default true.' However, the description doesn't clarify anything about the `contenuto` format beyond what the schema already says ('Uno o più <Item .../>'), and there's no guidance on what the return value looks like in either mode (dry=true vs false). Reasonable but incomplete parameter-level coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is precise about what the tool does: 'Applica un pacchetto AML' names the verb ('applica') and the resource ('pacchetto AML'). It immediately differentiates itself by stating it is 'l'inverso di aras_export_aml' (the inverse of aras_export_aml), making its relationship to siblings explicit. The dual-mode behavior (dryRun vs. execute) further clarifies 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit naming of aras_export_aml as its counterpart effectively tells an agent when this tool is the right choice (importing/pushing a package) vs. when to use the sibling. The description clarifies the dryRun default and that it a) analyzes content and b) reports destructive action count before executing. It doesn't enumerate possible conditions where an import would be invalid or explain whether there are more appropriate state-changing siblings, but the inverse relationship to its export counterpart provides enough guidance 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description largely carries the behavioral disclosure burden. It adds useful context—these are internal Aras queries available for reuse—but does not state whether the tool returns all queries, includes system queries, or any listing details. The behavior is predictable (a list operation), so the gap is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundancy. The resource type is front-loaded and the examples add practical value. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool, the description covers what is being listed and gives representative example query names. It could be more explicit about the return value or that it lists all available queries, but it is sufficient for an agent to know what this tool provides before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline is 4. The description does not need to explain parameter semantics since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific resource: saved Query Builder queries ('Query salvate del Query Builder'). It gives concrete examples like 'PE_BomStructure' and 'Aras.Resolution.LatestReleased', making the subject unmistakable. However, it does not explicitly differentiate from the similar sibling aras_list_saved_searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains these are pre-packaged queries that Aras uses internally and that the agent can reuse, implying this tool is for discovering reusable queries. It does not mention when to prefer aras_list_queries over aras_list_saved_searches or aras_describe_query, leaving the selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It clearly reveals the write operation (add/remove) and explains the consequence of granting a role, which is the core behavior. It does not mention prerequisites, side effects, idempotency, or error conditions, but the mutation itself is transparently described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the operation before providing a concrete example. No filler or redundant information; every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter mutation with no output schema, the description adequately covers the purpose, the specific use case (role granting), and the meaning of the relevant parameters. It lacks any mention of permissions or authentication needed for the operation, but the low complexity and clear schema make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes two of three parameters directly ('gruppo' and 'membro'), and the description's example maps them to meaningful values ('Aras PLM' and a user). The 'azione' parameter has no description but its enum values are self-explanatory, and the description explicitly references both add and remove actions. This offsets the 67% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: adds or removes an identity from a group, with a concrete example of role granting. It uses a specific verb and resource, making the purpose unambiguous. It does not explicitly differentiate from sibling tools like aras_create_group or aras_grant_permission, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'E' il modo di concedere un ruolo' implies when to use the tool (for role assignment), and the example clarifies a realistic scenario. However, there are no explicit when-to-use vs alternatives, no exclusions, and no mention of pairing with aras_get_identity_members for verification. Usage guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the main behavioral burden. The term 'Interroga' implies a read operation, and the OData mention sets expectations about filter syntax, but the description does not disclose output shape, pagination behavior, or whether results are limited. It 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundancy. The primary action is front-loaded, and the useful precondition advice appears second. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no output schema and no annotations, the description is compact but not fully complete. It gives working context but does not describe the return format, how pagination params interact, or any error-prone behaviors beyond property-name confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description reinforces the role of itemType and property names, but it adds little beyond what the filter/select/orderby/itemType descriptions already state. Slight value comes from framing everything as OData and advising about property-name lookup.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Interroga') and resource ('elementi di un ItemType') with OData syntax. It clearly communicates the core function, but it does not explicitly distinguish itself from siblings like aras_get_item or aras_run_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical routing guidance: if property names are uncertain, call aras_describe_item_type first. This is a clear 'before using this tool' instruction, though it does not address comparison with other query-like siblings such as aras_get_item or aras_run_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does this well by explaining that dryRun executes nothing, that the transition graph is traversed step by step, and that promoting a versionable ItemType changes the item's id. It does not mention all permission or reversibility details, but the key side effect is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core action, and immediately provides the dryRun distinction and the critical id-change warning. Every sentence contributes value without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a release operation with no output schema and no annotations, the description covers the intended behavior and a major side effect, but it leaves gaps: how to discover valid target states, what the non-dryRun response looks like, and how this relates to aras_promote_item. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with only dryRun documented. The description adds useful meaning for dryRun (shows path and required roles), implicitly defines statoTarget as the target state, and warns that id may change. However, itemType and statoTarget value formats remain undocumented, so the description only partially compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the operation: 'Rilascia un elemento portandolo allo stato target' (releases an item to a target state) and describes the transition-graph traversal. It is specific enough to identify the tool's function, though it does not explicitly distinguish itself from the similar sibling aras_promote_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied through the description: release an item to a target state, optionally using dryRun to preview the path and required roles. However, there is no explicit guidance on when to choose this tool over aras_promote_item or other workflow-related siblings, and no alternative exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool goes through AML EvaluateActivity and notes that it is disabled in read-only mode, providing some insight into its behavior. However, it does not mention potential side effects (e.g., notifications, irreversible state changes) or what happens after the vote is cast. Since there are no annotations, the description carries the full burden and falls short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, consisting of four short sentences. It opens with the main purpose and then provides necessary context about the AML command, the prerequisite lookup, and the read-only restriction. There is no redundancy or unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives some context: it mentions the prerequisite use of aras_get_workflow and the read-only restriction. However, it lacks details about return values, error handling, or the outcome of voting (e.g., whether it triggers re-approval or sends notifications). Given that there is no output schema and no annotations, the description is only partially complete for a tool that performs a state-changing action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes descriptions for 'path' and 'assignmentId', and the tool description indirectly explains that 'activityId' and 'assignmentId' can be obtained from aras_get_workflow. However, the 'commenti' parameter has no description in the schema and is not clarified in the tool description. Since the description adds only a hint about where to find IDs, it only partially enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it completes a workflow activity by selecting an exit path (e.g., 'Approve', 'Reject'). It also mentions the underlying AML EvaluateActivity command, which reinforces the purpose. It does not explicitly contrast with sibling tools, but the action is specific enough to distinguish it from read-only tools like aras_get_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use this tool: after using aras_get_workflow to find the activity and assignment IDs. It also states that it is disabled in read-only mode, which indicates when it should not be used. This gives clear context for usage, though it does not mention alternative tools for similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full behavioral disclosure burden and largely succeeds. It discloses that the tool attempts the entire creation sequence, reports step-by-step what succeeded, and runs a final verification that the ItemType accepts instances — setting honest expectations about partial success. It loses a point for not clarifying behavior on partial failure (e.g., whether partial state is cleaned up), but this is strong disclosure for an admin operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose, critical warning, and behavioral verification. Each sentence earns its place with zero fluff, and the risk warning is appropriately front-loaded right after the single-sentence purpose. Text in Italian is consistent with the resource naming, and every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an operation with no annotations, no output schema, and 6 parameters, the description covers creation semantics, the UI-only documentation caveat, required companion configurations (permission, TOC, Can Add identity), and end-to-end verification behavior. The only gap is explicit handling of partial setup failure and cleanup, but the disclosure is strong enough that an agent can set appropriate user expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage, the description partially compensates by giving semantic meaning to the behavioral params: 'default permission' maps to permissionName and 'identita' Can Add' maps to canAddIdentity. The remaining undocumented params (etichetta, proprieta, versionabile) are relatively self-evident. The description adds documented meaning to the two most semantically rich parameters, keeping it at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Crea un nuovo ItemType con le sue proprieta'' — a specific verb (creates), resource (Aras ItemType), and scope (with properties). This clearly distinguishes it from sibling tools like aras_list_item_types or aras_describe_item_type without needing to name them. However, it doesn't explicitly reference sibling differentiation, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The warning explains the tool exists because Aras only documents ItemType configuration via the UI (Administration -> ItemTypes), implying this tool fills the API gap and performs additional setup steps (default permission, TOC Access, Can Add identity). This gives good contextual grounding on when the tool is needed. However, it doesn't explicitly state when NOT to use it or name alternative tools, leaving exclusion conditions implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses what the tool returns (property schema plus relationships) and implies a read-only metadata operation, but it does not describe the output structure, error behavior, or permission implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no wasted words. The first sentence states the return value, and the second provides practical usage context, making it well front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only metadata tool, the description covers the essential purpose, output content, and when to call it. However, since there is no output schema, the description could have been more explicit about the expected response format or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already documents the only parameter with an example ('Part', 'Document', 'ECN'). The tool description adds no parameter-level detail, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the complete schema of an ItemType, including property data types, requiredness, and outgoing relationships. This distinguishes it from data-retrieval tools like aras_get_item or aras_query_items, but it does not explicitly name a sibling or define a negative scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: use this tool BEFORE writing queries or creating elements, so property names do not have to be guessed. It does not mention when not to use it or name a specific alternative, such as aras_list_item_types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool is a read-only inspection operation (describes structure) and implies it returns structural information. However, it doesn't disclose what the output format is, whether it requires any special permissions, or any side effects (though it's clearly non-destructive). The description is adequate but minimal; it doesn't add rich behavioral context beyond the obvious read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose and includes a usage directive. No wasted words. It's appropriately sized for a simple tool with one parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple inspection tool with one parameter and no output schema, the description is fairly complete. It tells the agent what the tool does, what it needs (the query name), and when to use it (before executing). The only gap is that it doesn't describe the return format, but given the tool's simplicity and the lack of an output schema, this is a minor omission. It could also mention that it's a read-only operation, but that's implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the parameter 'nome' is described as 'Nome della qry_QueryDefinition' (name of the qry_QueryDefinition). The description adds that the tool describes the query structure, which implies the parameter is the query name, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already documents the parameter fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose: it describes the structure of a saved query, including which ItemType it starts from and which parameters it accepts. This is a specific verb+resource ('describes a saved query structure') and distinguishes it from siblings like aras_run_query (which executes) and aras_list_queries (which lists). However, it doesn't explicitly name those siblings, so it's clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Da chiamare prima di eseguirla' (to call before executing it), which provides clear usage context: use this before running a query. It doesn't explicitly state when not to use it or name alternatives, but the 'before executing' instruction is a strong usage guideline. It could be improved by mentioning that aras_run_query is the execution counterpart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation, but it doesn't explicitly state that no changes will be made to the system, which is a minor gap. A definitive note on side effects would improve transparency, though the absence of write operations is generally inferred.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, avoiding unnecessary details or redundancy, and follows a clear, consistent format with other tools. It’s straightforward and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides basic context but doesn't explicitly cover when to use this subsequent to other tools or what to do with the result. The given context is narrow and could benefit from additional scaffolding like 'Use this to retrieve the inbasket; the returned items can be iterated as needed.' Without it, the context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema is an empty object, so there are no parameters to document. The description correctly reflects this by not inventing any, and the absence is clear from the schema; all possible inputs are covered, even if no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves the inbasket for the current user, leaving no ambiguity about its core function. However, it doesn't explicitly mention that the inbasket is read-only or what it contains, which could be inferred from similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance on when to use this tool vs others, offering no examples or differentiated scenarios. It's implied to be the go-to for fetching an inbasket, but the description doesn't explicitly outline selection criteria, making it unclear when to choose this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the tool's behavior thoroughly, including what it returns (current state, allowed transitions, missing role) and how it relates to underlying methods (getItemNextStates, promoteItem). It also clarifies the authorization failure mode, giving transparency beyond a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that is informative without being overly verbose. It front-loads the main purpose and then provides necessary context about authorization, maintaining a reasonable length. Some repetition occurs (mentioning the missing role twice), but it remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for an agent to understand when to use the tool and what to expect, including the authorization nuance. It does not specify output format, but since no output schema is provided, this is acceptable. The explanation of failed promotions covers an important edge case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes two parameters: id (no description) and itemType (only an example 'Part', 'ECR'). The main description does not explain what these parameters represent or how they relate to the item being queried. The example provides minimal context, but semantic clarity is largely missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieves the current lifecycle state, lists possible next states for the current user, and identifies missing roles that prevent promotion. It also distinguishes itself from related tools like promoteItem and getItemNextStates by including the authorization context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage scenarios (e.g., diagnosing why promotions fail due to missing roles) but does not explicitly state when to prefer this tool over alternatives like getLifecycleMap or promoteItem. It provides context but lacks direct 'use this when' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It adds useful context: the workflow is automatically created and includes all activities, statuses, and assignments. However, it does not explicitly state that the operation is read-only, nor describe side effects or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core resource and output content; the motivational use cases earn their place. There is no redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter getter, the description explains the output content and the key context that the workflow already exists. Without an output schema it could specify more structure or error cases, but it is adequate for selection and basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description only echoes that activities and assignments are included (mapping to conAttivita) and gives no new format, edge-case, or dependency semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('processo di workflow di un elemento') and the data returned (activities, status, assignees), and ties it to the user questions 'where is this change' and 'who is blocking it'. It is distinct from sibling lifecycle/history tools, though it lacks an explicit verb such as 'retrieves'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames when to use this tool: to answer workflow-progress and blocker questions. It also notes that Aras auto-instantiates the workflow, so there is no need to set it up. It does not name alternative tools or exclusion conditions, keeping it at a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. It indicates 'ricercabili per nome' (searchable by name), implying a read-only search operation, but it does not explicitly state safety, output format, pagination, or authentication requirements. It adds some value by specifying the name-based search, but leaves significant behavioral details unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the core purpose and a crucial relation to aras_aml_request. There is no redundancy or unnecessary detail, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters and no output schema. The description covers the primary purpose (search server methods by name) and notes their invocability, but it does not specify what the response contains (e.g., method names vs. full definitions) or how pagination works. For a simple list tool it is adequate, yet lacks enough detail to fully prepare an agent for the returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameter meaning. It mentions 'ricercabili per nome' which directly maps to the 'cerca' parameter, but it fails to describe the 'limite' parameter or clarify that 'cerca' acts as a filter on method names. The description provides only minimal guidance, leaving one of two parameters entirely underexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Metodi server definiti in Aras, ricercabili per nome' (server methods defined in Aras, searchable by name), clearly identifying the resource and primary action. The phrase 'utili per capire quale logica personalizzata esiste' reinforces its role as a discovery tool, aligning perfectly with the name aras_list_methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Utili per capire quale logica personalizzata esiste' (useful to understand which custom logic exists), defining the discovery use case. It also notes 'invocabili con aras_aml_request' (invokable with aras_aml_request), implicitly directing agents to use aras_aml_request for execution, thereby distinguishing this listing tool from its invocation sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the side effects of the operation: it performs a lock/version/unlock sequence, which is a key behavioral trait. It also notes that the operation is disabled in read-only mode. This is more transparent than many tool descriptions, though it does not mention failure modes or return values."
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main action and includes essential constraints. It wastes no words and is immediately understandable."
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While it captures the core purpose and side effects, it omits details about prerequisites (e.g., item must be versionable), potential errors, and the expected response. Given the tool's moderate complexity, the description provides decent context but is not fully complete."
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (id and itemType) with no descriptions. The tool description does not elaborate on what these parameters mean or how they relate to the revision creation. Since schema coverage is 0%, the description fails to compensate for this lack of parameter documentation."
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: creating a new revision of a versionable item. It explicitly mentions the lock->version->unlock sequence, which distinguishes it from other Aras tools like promote_item or release_item. The verb 'creates' is specific and the resource context (versionable item) is evident."
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need a new revision) but does not explicitly contrast with alternatives or state when not to use it. It mentions 'disabled in read-only mode', which is a usage constraint, but lacks explicit guidance on choosing this over other revision-related tools."
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only lookup ('trova TUTTI gli assiemi'), but never states that it is non-mutating or describes any side effects, permissions, or performance implications. Because it is a query, the risk is low, but the description omits any explicit behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the purpose and use-case in two short sentences, with a helpful analogy and sibling reference. Zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It explains when to use the tool (before modifying a part to see impact) and identifies the inverse sibling. The only gap is that it does not mention the default depth or that it is bounded, which is available in the schema, so minor. Overall sufficient for the agent to decide when to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters (100% coverage). The description adds the notion of 'any level' which actually conflicts with the schema's max depth of 10. This is a slight inconsistency, reducing clarity. Since schema covers the parameters well, the description adds little.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('risale' – climbs/traverses), the resource (BOM/assemblies), and the specific behavior (finds ALL assemblies that use a component at any level). It also distinguishes it from aras_get_bom as its inverse, making selection unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use case with a concrete example ('if I change this screw, what do I impact?') and explicitly positions it as the inverse of aras_get_bom. It doesn't give a formal decision rule for when to pick this tool over alternatives, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly warns that the tool returns only metadata and a download URL, that the server does not download or read file contents, and that uploads from an external client are rejected by Aras. This is unusually candid and leaves little room for the agent to assume content is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded and the critical 'metadata only' warning is clearly separated. The upload note is somewhat redundant ('not possible from external client' and 'must be uploaded from Aras interface') and includes implementation detail (JavaScript/C#), but overall the structure is scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter metadata-retrieval tool with no output schema and no annotations, this description is nearly complete: it names the input domain, the fields returned, and the post-retrieval action (authenticated URL fetch). It omits minor operational details such as pagination, ordering, or empty-result behavior, but an agent can invoke it correctly with the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (id has a description; itemType has only an enum), and the description adds the Document/CAD context that ties both parameters to the attachment scope. It does not, however, explain exactly how itemType and id combine, GUID formats, or any constraints beyond the enum, so compensation for the low coverage is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific resource — physical files attached to a Document or CAD — and enumerates the returned fields (name, size, MIME type, download URL). The explicit 'returns metadata, not content' note differentiates it from content-fetching operations such as aras_read_file, though it does not name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the tool is for metadata and a URL, and says content must be fetched separately by following the URL with an authenticated client. However, it never names the preferred sibling alternative (e.g., aras_read_file) or gives explicit conditions for choosing this tool over other attachment/document tools; the guidance on upload is tangential to selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses a critical behavior: out-of-list values appear valid to the schema but fail in Aras. However, it does not describe the return format (e.g., a list of values per property, a flat list, etc.) or any other behavioral nuances like error handling. While the warning is valuable, the disclosure is incomplete given the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. The purpose is front-loaded, and the critical usage warning is included efficiently. It is exemplary in conciseness and structural clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and the validation caveat, but does not explain the return format or any limitations (e.g., does it return values for all list properties or only a specific one?). For a simple one-parameter tool with no output schema, this is a noticeable omission. The description is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes itemType with examples ('Part', 'Document'), and the description adds contextual meaning (it is used to fetch list values for that item type) but does not go beyond the schema. Since schema description coverage is 100%, a baseline score of 3 is appropriate—the description adds no further parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns allowed values from list-type properties of an ItemType, with concrete examples (make_buy, unit, drawing_size). It is specific about the resource (list properties) and the action, and no sibling tool appears to serve this specific purpose, so it is easily distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call this tool BEFORE creating an item, and explains why: out-of-list values pass schema validation but are rejected or ignored by Aras. This provides a clear usage context. It does not mention alternatives or exclusions, but the guidance is sufficient for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds useful context by revealing that Aras returns permission denials as a generic 500 error rather than 403, implying why this tool is needed. However, it does not state whether the tool performs a read-only operation, describe the output format, or mention any side effects or prerequisites. For a simple get tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and a practical diagnostic hook. Every sentence earns its place; there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and no output schema, so complexity is low. The description explains the purpose and the error scenario, but it does not specify what the returned data looks like (e.g., a list of identities and a boolean for current user). While not strictly necessary given the simplicity, an agent might benefit from knowing the response format to parse it correctly. Overall, it is usable but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'itemType' with an example ('Manufacturer', 'Part'), so schema_description_coverage is 100%. The description does not add any additional meaning or constraints beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to identify which identities can add, modify, or delete instances of an ItemType, and to check if the current user is included. It also provides a concrete diagnostic use case ('why can't I create this'), which distinguishes it from the many sibling tools by focusing on permissions and user membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as the answer to a specific troubleshooting question ('perche' non riesco a creare questo'), giving an implicit when-to-use. It does not name alternatives or exclusions, but the context of permission checking is clear enough for an agent to route appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the output includes content types and that typical instances contain standard dashboards, giving some insight into the result. However, it does not describe the return format, ordering, pagination, or any potential limitations, so transparency is incomplete but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two sentences: the first states the core purpose, and the second adds relevant context about typical instances. It is front-loaded with the main function and contains no unnecessary words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter, no-output-schema tool, the description is complete. It explains what the tool returns (dashboards with content types) and provides typical examples, which is sufficient for an agent to know what to expect. There is no missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to explain. The baseline for zero parameters is 4, and the description does not need to add parameter-specific meaning. It does not miss anything because there are no parameters to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists configured dashboards ('Cruscotti configurati in Aras') and the content types they host, which is specific and distinguishes it from siblings like aras_list_reports or aras_list_item_types. The verb 'list' is implied by the name and reinforced by the description, so an agent can easily understand the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly indicate when to use this tool over alternatives, nor does it name any sibling tools or provide exclusion criteria. It only mentions that standard instances have several dashboards, which gives context but no direct guidance on selecting this tool versus others. This falls short of the explicit when/when-not guidance expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the recursive explosion behavior, the returned tree structure (components with quantities and cumulative quantities), and the read-oriented framing 'restituendo'. However, it does not mention depth-limit behavior, cycle handling, or explicitly declare read-only safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first front-loads the core behavior and output, the second provides usage context. Every clause earns its place and nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two fully documented parameters and no output schema, the description covers the purpose and conceptually describes the return value (component tree with quantities and cumulative quantities). The main gap is that, without an output schema, the exact return structure is not specified, and edge cases like depth limits or cycles are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — both partId ('id della Part radice') and depth ('Livelli di esplosione', default 3, max 10) are documented in the input schema. The description adds little parameter-specific meaning beyond implying recursion relates to depth, so the baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Esplode la distinta base (BOM) di una Part in modo ricorsivo' — and specifies the output: the component tree with quantities and cumulative quantities. The question examples ('da cosa e' composto questo prodotto') clearly distinguish it from reverse-lookup siblings like aras_where_used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames when to use the tool: 'E' il modo corretto di rispondere a domande tipo "da cosa e' composto questo prodotto" o "quanti pezzi di X servono in totale".' This gives clear selection context, but it does not name alternative tools or state when-not conditions explicitly, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral transparency burden. It does disclose the core behavior: returning a full graph of states and transitions. However, it does not explicitly state side-effect-free behavior, authentication/permission requirements, or any response-size expectations, leaving some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two focused sentences that front-load the key output and then explain its value. Every clause contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description gives a clear idea of the returned content and the purpose. A more detailed note on expected response structure or potential exceptions would improve completeness, but the description is adequate for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the one parameter has a clear description with examples. The tool description itself doesn't add extra parameter semantics, but it doesn't need to because the schema already provides sufficient detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: it retrieves the complete graph of a lifecycle, including all states, transitions, and required roles. It also gives the intended use case, distinguishing it from narrower lifecycle-related tools like aras_get_lifecycle_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains why an agent would use the tool: to understand which lifecycle paths exist and which roles can traverse them. It does not name specific exclusions or alternative tools, but the context is strong enough to select it for lifecycle-path analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does a good job: it discloses that the tool returns all generations, not just the current one, and lists the fields shown (revision, state, lock holder, current). It also explains the config_id sharing mechanism, which helps the agent understand what the result represents. It does not explicitly state read-only safety or error/authorization behavior, but the read-oriented nature is strongly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the main purpose front-loaded and the supporting Aras domain context in the second sentence. Every sentence earns its place, with no wasteful filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a solid high-level view of the tool's behavior and its Aras data-model context, but with no output schema and no annotations, some important details are missing: the exact response shape, ordering of revisions, behavior for non-versionable items, and permission requirements. It is adequate for basic invocation but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining that generations are distinct rows sharing config_id and that a normal query returns only the current generation. This clarifies that the id parameter can be any generation's id, which goes beyond the schema's one-line description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the complete revision history of a versionable item, including revision, state, lock holder, and current revision. It distinguishes itself from a normal Aras query that returns only the current generation, but it does not explicitly differentiate from sibling tools like aras_get_history or aras_get_item, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: when you need all generations rather than only the current one. It explains the Aras generation model and contrasts the behavior with a normal query, but it does not explicitly name alternatives or state exclusions, so usage guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It discloses that the catalog contains all server message templates, that matching is by substring, and that results include the code and meaning. It does not cover match limits or edge cases, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences front-load the purpose and add one crucial behavioral detail. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a lookup with no output schema, the description gives enough to start searching and says the result will trace back to code and meaning. However, it leaves the exact result shape unspecified and never explains 'limite', so a caller still has some ambiguity about both limit semantics and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents 'testo' with an example, and the description mostly restates that substring idea. The optional 'limite' parameter has no schema description and is never mentioned in the description, so with only 50% schema coverage the agent must infer its meaning from the name and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (Aras UserMessage catalog), a specific action (search), and the intended goal (deciphering an opaque error). This clearly distinguishes it from generic siblings such as aras_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context: use when an error from Aras is opaque, and search by part of the received text to recover code and meaning. It does not explicitly name exclusions or alternatives, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the tool returns data and that XSL transformation is only for client-side rendering, implying a read-only behavior. However, it does not explicitly state side effects or permissions, though the read-centric nature is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—two sentences—and front-loads the core purpose. It avoids unnecessary detail and directly addresses the tool's main function and a key parameter, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema, the description covers the essential function and parameter context. It does not specify the return format or error handling, but for a straightforward report execution tool, it is adequately complete. The missing details on massimo and nome slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the purpose of contestoId (the context element id for parametric reports) but does not clarify nome or massimo. The schema only provides types and constraints, so the description adds meaning for one parameter but leaves the other two undefined, giving partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a report and returns raw data, distinguishing it from XSL-based graphical rendering. It also notes that many reports are parametric, giving a clear sense of its primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage instructions for the contestoId parameter ('passa contestoId con l'id dell'elemento su cui eseguirlo') but does not explicitly compare with sibling tools like aras_run_query or aras_get_item. It implies when to use it (when you need report data) but lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It transparently explains that the tool creates a User, relies on Aras's auto-generated Identity alias, and writes Member rows for group membership. It also discloses a specific failure mode ('cannot be greater than 1') for creating a second alias, which is useful operational detail beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: three sentences, front-loaded with the main purpose, followed by essential Aras-specific mechanics and a caveat. Every sentence earns its place and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of creating an Aras user, the description covers the non-obvious three-step process and the critical alias limitation, which is enough for correct invocation. It does not mention duplicate-user behavior, required permissions, or return values, but these are not fatal given no output schema and otherwise clear guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, with only 'gruppi' documented in the schema. The tool description adds meaning only for group membership, explaining that enrollment happens via Member rows, but it does not compensate for the low coverage of the other five parameters such as login, nome, cognome, email, and azienda.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Crea un utente e lo iscrive ai gruppi indicati.' This clearly identifies the tool as user creation plus group enrollment, which distinguishes it from sibling tools like aras_create_item, aras_create_group, or aras_manage_membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context by explaining Aras' three required steps (User, auto-generated Identity alias, Member rows) and warns that creating a second Alias fails. It does not explicitly name alternative tools or state exact when-not-to-use conditions, but the guidance is sufficient for an agent to understand when this composite tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the download mechanism, fallback behavior, return types per format, and the OCR limitation for scanned PDFs. It doesn't mention error cases (e.g., file not found, permission issues) or whether the operation is read-only, but the read intent is clear from 'LEGGE IL CONTENUTO'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, covering purpose, mechanism, return types, and a limitation in a few sentences. It's front-loaded with the core purpose. Slightly verbose with the Italian phrasing but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no output schema and no annotations, the description covers the key behaviors: what it returns for different formats, the fallback, and the OCR limitation. It doesn't specify error handling or size limits beyond maxCaratteri, but the essential information for an agent to call it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds context that fileId comes from aras_get_files and that maxCaratteri limits returned text, but these are minor additions. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads file content (not just metadata), specifies the resource (File('<id>')/$value) and the fallback endpoint, and distinguishes it from aras_get_files which is for finding IDs. It also enumerates the return types for different formats, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use aras_get_files to find the ID, which is a clear prerequisite. It also explains behavior for scanned PDFs (says OCR needed instead of returning empty). However, it doesn't explicitly state when NOT to use this tool or mention alternatives for metadata-only needs, though the contrast with aras_get_files is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about the action (voting active activity) and the dryRun preview. It warns that pending activities have no effect, but does not mention potential side effects like state transitions after voting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and well-structured. It covers the essential behavior without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fairly complete for a specialized tool. It explains the purpose, the condition, and the dryRun behavior. It does not describe the return value, but that is not required without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes 'via', and the description explains dryRun. However, 'changeId' and 'commenti' are not clarified, leaving gaps. Overall, the description adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (advance) and the resource (ECR/ECN), specifying that it votes the active activity. This distinguishes it from the sibling tool aras_vote_activity, which is more general.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the condition (only one active activity, pending ones are downstream) and the dryRun feature, giving practical guidance. It does not explicitly compare with vote_activity, but the specificity implies when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing destructive behavior. It declares deletion, distinguishes purge from delete, requires explicit confirmation, and warns about read-only environments. It stops short of stating irreversibility or required permissions, but the core behavioral profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and then constraints; every sentence carries a distinct piece of information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive 5-parameter tool with no annotations and no output schema, it covers the essential prerequisites, mode semantics, and confirmation requirement. It does not describe the return value or the exact behavior when aras_plan_delete reports warnings, but the remaining gaps are secondary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, and the schema already documents the modo enum and the conferma Boolean. The description reinforces that 'delete' affects all generations and adds the plan-delete prerequisite, but it adds little meaning for id, itemType, or ignoraAvvertenze beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a precise action ('Cancella un elemento') and clarifies the two destructive modes ('purge elimina solo la generazione indicata, delete elimina TUTTE le generazioni'), which makes the tool's role and scope unambiguous relative to sibling create/update/plan tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit prerequisite ('Chiama prima aras_plan_delete') and an environment exclusion ('Disabilitato in sola lettura'). It does not enumerate when not to use the tool, but deletion has no direct sibling alternative, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral transparency burden. It does disclose that inherited identities are included, but it does not explicitly state that the operation is read-only, how the configured user is resolved, or what the returned identities can be used for beyond diagnostic context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, purposeful sentences: the first defines what is returned, and the second explains the diagnostic use case. There is no filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument getter, the description is almost complete. It defines both the tool's content and intended purpose. However, the lack of any output schema or return-shape hints leaves minor uncertainty about the exact structure of the returned identities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is no parameter ambiguity, and the description does not need to add parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: the configured user's identities, including group-inherited ones. It also gives the intended use case — understanding why a promotion or write is rejected — which helps differentiate it from identity-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use context: when a promotion or write operation is refused. It does not mention alternatives or explicitly say when not to use it, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the tool's behavior (returns relationship rows) and gives examples, but it doesn't disclose details like pagination behavior (though the 'top' parameter hints at it), whether it returns all relationships or only direct ones, or any potential side effects. Since it's a read operation, the lack of destructive warnings is fine, but more behavioral context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and front-loads the core purpose with examples. It also includes a useful pointer to another tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema), the description is fairly complete. It explains what the tool does, gives examples, and points to a discovery mechanism. However, it doesn't mention the return format or any limitations (e.g., max 500 results), but the schema covers the 'top' parameter. For a read-only relationship query, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (two of three parameters have descriptions). The description adds value by explaining the purpose of the tool and giving examples of relationshipType values, which helps understand the parameters. However, it doesn't add much beyond the schema for the 'top' parameter, which is self-explanatory. The description compensates for the missing parameter description (top) by implying its use through the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it returns rows of a relationship from a source element, with concrete examples ('Part Document', 'Part Changes'). It distinguishes itself from siblings by focusing on relationships retrieval, and even points to aras_describe_item_type for discovering relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (to get relationship rows from a source element) and gives examples. It also suggests using aras_describe_item_type to discover relationships, which is a helpful pointer. However, it doesn't explicitly state when NOT to use this tool or mention alternatives like aras_get_bom or aras_where_used, which could be relevant for similar queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses its sources (field knowledge and instance catalog), its exclusion of official docs, and its intent to answer questions. However, it does not explicitly state the tool is read-only or side-effect free, though the 'CONSULTA' prefix implies no mutation. This is a minor but notable omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with an imperative call to action ('CONSULTA PRIMA DI TENTARE') and is efficiently structured: what it does, its sources, why not official docs, and when to use. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's advisory role and simple parameter set, the description covers the essential context: when to use, what it answers, and its sources. It does not describe the return format, but no output schema exists, and the absence is acceptable for a text-based Q&A tool. Overall, sufficiently complete for an agent to decide when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters. The description adds value by explaining the two sources (verified field knowledge and instance catalog), which directly maps to the 'conIstanza' flag. This contextual link enhances parameter understanding beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('risponde a') and resource ('come si fa X su Aras da un client esterno' and 'perche' questo errore'). It clearly differentiates itself from official Aras documentation and implies a unique consultation role distinct from direct data operations. While it doesn't name sibling tools like aras_lookup_error, its purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: 'Chiamalo quando una chiamata fallisce in modo incomprensibile, o prima di tentare qualcosa di insolito.' It also gives a negative guideline (do not follow official docs). However, it does not mention alternatives or when not to use this tool beyond those conditions, which leaves some room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It clearly frames the operation as a read-only text search and details the scope of what is searched. A 5 would require an explicit statement about non-mutation or auth, but for a search tool the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler, and the tool's core purpose is front-loaded. Every sentence adds scope, field details, or usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward search tool with well-documented parameters, the description is largely complete: an agent can decide when to use it and how to invoke it. The main gap is that no output shape is described, but the result of a search is natural enough that this is not a blocking omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100 percent, so the input schema already documents term, perType, and itemTypes with examples and defaults. The description contributes extra context about fields and intended use but largely repeats what the schema already expresses.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and a specific resource: it performs a cross-type search over multiple Aras item types and enumerates the textual fields and types searched. This clearly distinguishes it from item-specific tools like aras_get_item or aras_query_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool when you do not know which item type contains the term, and explains that Aras lacks a global search. It does not explicitly name alternative search tools for when the type is known, but that condition is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds meaningful context about the date-based mechanism and that this is the effectivity Aras always populates. However, it does not disclose the return shape, how missing dates are handled, or whether invalid partIds produce errors, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core function first, then the differentiating nuance, then the alternative. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity check tool with two well-documented parameters, the description provides enough context to select and invoke it correctly. It could have mentioned the result format, but the core purpose, method, and sibling distinction are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds value beyond the schema by explaining that validity is determined by effective_date and superseded_date, which clarifies how the 'data' parameter maps to the underlying Aras effectivity logic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Verifica se una Part era valida') and identifies the resource (Part) and the temporal criterion (a certain date). It also explicitly differentiates itself from aras_get_effectivity_config, so an agent can distinguish it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the exact use case: checking date-based effectivity using effective_date and superseded_date. It also gives an explicit alternative with the condition: use aras_get_effectivity_config for configurable model/unit-based effectivity. This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and reveals a non-obvious side effect: dependent items are created inline within the relationship when dependentProperties is used. It also discloses that the tool is disabled in read-only mode. It does not mention return shape or permission requirements, but the key surprising behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no wasted words; the main purpose and resource are front-loaded. Every sentence contributes either core meaning, parameter guidance, or a usage constraint, and the dependentProperties rule is compressed into one clear sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter mutation tool with no annotations and no output schema, the description is quite complete: it covers what is created, the inline dependent-item mechanism, the primary use case, and a read-only constraint. The main gaps are the return value of the created relationship and whether relatedId and dependentProperties are mutually exclusive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the baseline is 3. The description adds real value by explaining that dependentProperties is an alternative to relatedId and causes inline item creation, which is not apparent from the schema alone. It also reinforces relationshipType examples like 'Part Document' and 'ECR Affected Item', making the parameter usage clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Crea una riga di relzione fra due elementi' and gives concrete examples like 'Part Document' and 'Part BOM'. It also clearly differentiates the tool from siblings by stating it is the only way to link an Affected Item to an ECR/ECN.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('E' l'unico modo di collegare un Affected Item a una ECR/ECN') and explains the dependent-element routing rule: pass dependentProperties instead of relatedId when dependent items cannot be created first. It does not name alternative sibling tools for more common relationship creation cases, leaving a small gap in when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It discloses that the tool performs a listing operation (read-only implied by 'Elenca'), that filtering is supported via 'search' and 'kind', and that the search is 'ricerca tollerante su nome ed etichetta' (tolerant match on name and label). It does not explicitly state read-only status or output behavior, but the core listing behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences in Italian with zero filler. The first sentence states the core purpose and the second delivers filter guidance and usage timing. Everything present earns its place; no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate schema richness (3 params, 67% described) and lack of output schema, the description covers purpose, filtering, and usage timing well. The main gap is that it does not describe the output shape (e.g., what the returned list contains) or default result size behavior, though the limit default of 50 partially hints at this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (kind and search have schema descriptions; limit does not). The description adds meaning beyond the schema by clarifying that 'search' performs a tolerant match on both name and label, and that both 'search' and 'kind' serve as filters. The limit parameter is not described, but its schema already carries default/min/max constraints, providing sufficient guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Elenca' = lists) and a specific resource (ItemType). It clearly distinguishes the tool from data-querying siblings by saying 'Usalo PRIMA di interrogare dati, per scoprire il nome esatto del tipo' (use it BEFORE querying data, to discover the exact type name), setting it apart from tools like aras_query_items or aras_get_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage timing ('Usalo PRIMA di interrogare dati' = use it before querying data) and explains the purpose of discovery. It also instructs on how to narrow results via 'search' or 'kind'. It does not explicitly contrast with aras_describe_item_type or other similar discovery tools, but the 'use before querying' directive is a clear, actionable guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states the tool does NOT delete (SENZA cancellarlo), clarifying its non-destructive nature. It also discloses the two modes (purge/delete) and what it analyzes (generations, release, block, references). It does not detail return format or error behavior, but the core behavioral transparency is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The primary purpose (non-destructive analysis) is front-loaded, followed by the key behaviors and the purge/delete distinction. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description covers the tool's purpose, its non-destructive nature, the parameters' semantic differences, and the types of information returned (generations, release, block, references). It could specify the response format or prerequisites, but for a planning tool it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description adds meaning to the 'modo' parameter by explaining purge vs delete. It also clarifies the purpose of the 'relazioni' parameter (which relations are checked) and implies the context of id/itemType. The description compensates for the partially covered schema by explaining the tool's operation, though id/itemType remain self-evident but undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes the impact of deleting an element without performing the deletion. It lists specific outputs (generations lost, released/blocked status, references) and distinguishes between purge and delete. This is a specific verb (ANALIZZA) on a resource (deletion impact) and distinguishes itself from aras_delete_item among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs the agent to always call this before deleting, which is a clear when-to-use condition. It also explains the difference between purge and delete, aiding parameter selection. However, it does not name the alternative tool (aras_delete_item) for the actual deletion step, though the intent is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden and mostly delivers: it discloses global scope across all BOMs and explicitly states that dryRun (default) previews the affected assemblies before any change. It would be even better with a warning about irreversibility or permission requirements, but the dry-run default significantly mitigates risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise clauses deliver the core functionality, global scope, and default dry-run behavior. No filler words, and the most important facts are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, no-output-schema tool, the description is nearly sufficient: the agent knows the purpose, the required parameters from the schema, the global scope, and the default safe behavior. The only missing context is what dryRun=false precisely returns once the replacement is executed, and potential permissions, but this is enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents vecchio and nuovo as item numbers, and the description adds a meaningful behavioral meaning to dryRun, explaining that it shows affected assemblies first. This compensates for the missing dryRun field description in the schema, though vecchio/nuovo add no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: replacing one component with another across ALL BOMs that use it. It also names real use cases—obsolescence and second sourcing—and the phrase 'in TUTTE le distinte' clearly differentiates this global operation from per-BOM or single-item tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates when to use this tool: when a component is obsolete or being second-sourced and needs global replacement. It does not explicitly name alternatives or say when not to use it, but the 'TUTTE' scope and the examples make the intended use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses that it does not actually run the query, a key behavioral trait not covered by annotations, and explains that it returns the structure instead, providing transparency about its capabilities and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence structure, front-loaded with the primary purpose, and includes necessary limitation context without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a high-level idea of the return (query structure and tool suggestions) but lacks specifics on the format or content of the returned structure, leaving some ambiguity since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not elaborate on the meaning or usage of parameters like 'nome', 'maxRighe', or 'parametri'. Given the minimal schema, this lack of explanation leaves ambiguity about how to specify the query name or parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool attempts to execute a saved query but, due to a known limitation, returns the query structure and suggests alternative tools. This distinguishes it from siblings like aras_query_items that actually perform queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions that execution is not possible from an external client and directs users to alternative tools for data retrieval, making it clear when to use this tool (to get the structure) and when to use others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses that the SOAP envelope is automatic, that raw AML is executed, and that write actions are blocked to read-only. It does not mention response format or error behavior, but the core safety and execution behavior are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose and scope. Every sentence contributes: what it executes, when to use it, what to pass, and what is blocked. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter escape-hatch tool with no output schema, the description is sufficiently complete. It covers invocation style, intended usage, safety constraints, and scope. The schema provides the example, so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema provides a concrete example for itemXml. The description adds value by clarifying that the caller should pass only the <Item .../> fragment and that the SOAP envelope is handled automatically, preventing callers from wrapping the input themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('esegue AML grezzo contro InnovatorServer.aspx') and gives concrete use cases such as query logic not expressible with $filter and server methods. It clearly positions itself as the raw/escape-hatch tool distinct from the higher-level sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this only for what OData does not cover, listing examples like $filter limitations, server methods, and special actions. It also excludes write operations by noting they are blocked, but it does not name specific alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the output (database, user, number of ItemTypes) and implies a read-only connectivity check, making behavior transparent without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, providing essential information in two sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a ping-type tool, the description covers its purpose, usage scenario, and expected output, making it complete for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts no parameters, so there is nothing to explain beyond the schema. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to verify the connection to Aras Innovator and return specific connection details (database, user, item type count). It also provides a use-case hint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use first if something doesn't work, providing clear guidance on when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![aras-plm-mcp MCP server](https://glama.ai/mcp/servers/Erryb95/aras-plm-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Erryb95/aras-plm-mcp)

Score Badge

Copy to your README.md:

[![aras-plm-mcp MCP server](https://glama.ai/mcp/servers/Erryb95/aras-plm-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Erryb95/aras-plm-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Erryb95/aras-plm-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server