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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely new context by spelling out the content of the result (groupings, presentations, secondary views, value sets, current view state) and noting it can be scoped; the 'read-only, no undo step' clause largely restates the annotations rather than adding to them.

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

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

Two dense sentences that are front-loaded with the return content and then the usage instruction. Efficient and free of filler, though the first sentence is long and packs a lot of enumeration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't document return values, yet it still frames what the listing contains and when to use it. Combined with 100% schema coverage and full annotations, an agent has everything needed to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema description already documents the single 'view' parameter, its enum values, and the rationale for scoping. The description only reinforces the same point ('pass view to get only the one view you need'), which is useful routing but adds no semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Reports/Lists) and resource (supported analysis options: views, groupings, presentations, secondary views) and enumerates exactly what is returned. It distinguishes itself from siblings by naming rillsoft_view_state_apply as the natural consumer of this information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call this before rillsoft_view_state_apply to learn which combinations exist, and gives a concrete alternative path ('pass view to get only the one view you need'). Both the when-to-use and the when/what-else are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the flat YAML output shape, the view-scoped (not project-wide) behavior, and 'no undo step.' Return details are not repeated, which is fine since an output schema exists.

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

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

Front-loaded with the verb+resource+format, followed by scope and dependency information that earns its place. Slight redundancy: 'Read-only' restates readOnlyHint and 'It takes no parameters' restates the empty schema, but the overall structure is tight and non-padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with an output schema, the description supplies everything an agent needs: scope, output format, the view-state prerequisite tools, and the fact that no undo exists. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the schema to document and the baseline is 4. The description sensibly confirms 'It takes no parameters,' which is the only parameter-relevant statement available.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource+format: it 'Reads the resource or capacity view currently visible as a flat YAML report.' It also defines the scope precisely ('that one visible view, not the whole project'). It does not contrast against the sibling report tool rillsoft_variance_report_get, keeping it just 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational context: which view is read comes from rillsoft_view_state_get and rillsoft_view_state_apply switches it, so the agent knows the prerequisite chain. However it does not state when to prefer this tool over alternatives such as rillsoft_variance_report_get, so no explicit exclusions are present.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real value beyond them: it localizes the destruction to the replaceAll:true path, notes the portfolio refusal, and mentions 'One undo step' (reversibility). It does not give a return payload or what the new baseline looks like, but the output schema covers that, so this is close to complete.

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

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

Four tight sentences, each earning its place: core action, the destructive flag path, sibling routing, and portfolio refusal plus undo. Front-loaded with the verb and the destructive caveat early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with an output schema, it covers the action, the destructive branch, reversibility ('one undo step'), a domain restriction (no portfolio baselines), and how to reach related tools. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description still adds meaning beyond the schema by attaching the destructive consequence to the replaceAll:true flag and clarifying that the created baseline is selected. This makes the flag's side effect explicit rather than just a boolean description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('creates a baseline') and resource with concrete semantics: a snapshot of the current project state that also gets selected. It explicitly distinguishes itself from rillsoft_baseline_select and rillsoft_variance_report_get, so the agent can route between baseline siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use alternatives: switching baselines goes through rillsoft_baseline_select, comparison through rillsoft_variance_report_get. It also names a when-not condition ('Refused in a portfolio'), which no sibling sibling makes redundant. Nothing is left to inference.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses that selection falls back to the dynamic baseline, that only the snapshot is removed while project planning data stays intact, that portfolios are refused, and that the action is 'one undo step'. These are exactly the side effects and reversibility facts an agent needs.

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

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

Four short sentences, front-loaded with the action and consequence, each carrying distinct information (fallback, data preservation, sibling routing, portfolio restriction, undo). No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering the safety profile and an output schema present, the description supplies the remaining behavioral context - reversibility, data impact, and environmental restriction - leaving nothing material for an agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% - the number parameter is fully documented as coming from rillsoft_baseline_list, which the description echoes. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Deletes) and resource (a baseline), then distinguishes it from the sibling rillsoft_baseline_list for enumeration. An agent can immediately tell this is the removal operation versus create/select/list in the baseline family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative (listing goes through rillsoft_baseline_list) and gives a clear when-not condition (refused in a portfolio, no baseline exists there). It lacks explicit guidance on when to delete versus re-select, but the routing to the relevant sibling is clear.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so 'Read-only, no undo step' is partly redundant, but the 'no undo step' phrasing adds that the call does not create a history entry. The domain rule 'Number 0 while baselines exist means the dynamic baseline' is genuine behavioral context not present in any structured field.

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

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

Three short sentences, front-loaded with the resource and return shape, with no filler. The dynamic-baseline rule is dense but earns its place because it is non-obvious.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, an output schema covering return values, and annotations covering the safety profile, the description is essentially complete; the only omission is any hint of when to prefer this over the other baseline_* tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies; the description correctly spends no space on argument semantics and instead describes what is returned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Reads') and resource ('the baselines of the project') and even enumerates the returned fields (number, name, uuid) plus the active selection. An agent can distinguish it from baseline_create/delete/select by the read verb, though the description never explicitly names those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: it reads baseline state, so an agent infers 'use this to inspect baselines before selecting or deleting one.' No explicit when-to-use, prerequisites, or named alternatives (baseline_select, baseline_delete) are given.

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

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

Annotations already declare idempotent=true and destructive=false, and the description usefully adds that the operation is a single undo step and that it is refused in a portfolio (a real error condition). It stops short of describing what happens to the previously selected baseline, but the added context is substantive.

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

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

Three tight sentences, front-loaded with the core action, then the boundary with siblings, then the refusal condition and undo behavior. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. The description covers the mutation, its scope, sibling boundaries, the undo cost, and the failure case, which is everything an agent needs to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself explains the 'number' parameter including the 0 = dynamic baseline semantics. The description adds no parameter-level detail beyond that, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Selects the baseline') and scopes it to the planned-versus-actual comparison. It explicitly distinguishes itself from the sibling tools that create/delete baselines and the one that reads the comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternatives (rillsoft_baseline_create, rillsoft_baseline_delete, rillsoft_variance_report_get) with the condition that selects each, and states an explicit exclusion: it is refused in a portfolio. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds two genuinely non-obvious behaviors on top: the implicit default weekly model (Mon–Fri 08:00-12:00;13:00-17:00) and the transactional precondition requiring an open unit of work.

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

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

Two short clauses, no filler, and the most surprising fact (the implicit default weekly model) is front-loaded. The trailing precondition is terse to the point of being slightly cryptic, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param mutation tool with a full schema, an output schema, and annotations, the description covers the two things structured data can't: implicit defaulting and the required transactional context. It omits error behavior and how the created calendar is identified, which are minor given the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by defining the meaning of an omitted 'week' parameter — a default value the schema does not state. That is real added semantic value for the one parameter whose absence matters most.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a calendar') and immediately clarifies the default modeling behavior when 'week' is omitted. It does not name sibling tools (rillsoft_calendar_update, rillsoft_calendar_source_import), so an agent must infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Inside an open unit of work only' is a real precondition that tells the agent when the call is legal, which is more than most definitions offer. However, there is no guidance on choosing this tool over calendar_source_import or calendar_update, and no statement about what to do if no unit of work is open.

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

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

Goes well beyond the destructiveHint annotation by disclosing the referential-integrity rule (refused and named when referenced, because the pool reference would dangle), the invariant that the last calendar of a pool survives, and the requirement to be inside an open unit of work. These are exactly the multi-step and rollback-relevant facts an agent needs before invoking a destructive operation.

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

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

Four short sentences, front-loaded with the core action and then the failure and invariant clauses in priority order. The clause 'that reference lives inside the pool and would point nowhere' is slightly convoluted but earns its place by justifying the refusal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description still covers refusal behavior, invariants and transaction scope. It omits permission/authorization requirements, but otherwise the destructive path is adequately framed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema itself states 'give exactly one of id, code and name', so the parameter contract is fully carried by structured data. The description adds nothing about the identifier options, which matches the baseline of 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Deletes a calendar'), which is unambiguous and clearly distinct from the create/update/list siblings. It does not explicitly name an alternative, but the delete semantic is not confusable with any sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real preconditions — the call is refused when an idref_calendar references the calendar, and it must run 'inside an open unit of work' — which shapes when the call can succeed. However, it never contrasts with calendar_update or any sibling, and it does not explain how to resolve a refusal, so guidance 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description reinforces this with "Read-only, no undo step." Beyond the safety profile it adds genuine domain behavior: what an empty weekday slot means (a day off) and that exception days cover public and special days. It does not describe pagination or result shape, but that is partly covered by the output schema.

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

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

A single dense sentence that front-loads the verb and the returned data model, with the read-only caveat appended. Every clause carries information (weekly scheme, sun..sat order, empty = day off, exception day types), though the parenthetical stacking makes it slightly heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering the safety profile and an output schema covering the return structure, the description supplies the remaining domain context an agent needs: what a calendar record consists of and what the period filters delimit. Only the routing against sibling calendar tools is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters, including the id source and the DD.MM.YYYY hh:mm formats. The description only echoes the period-scoping idea ("within the period"), adding no syntax or default behavior beyond what the schema states, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Reads calendars of the master data") and enumerates what the calendars contain: the weekly scheme with shifts per weekday and the exception days. That is far more specific than the bare title, though it never names how it differs from near siblings such as rillsoft_calendar_source_get or rillsoft_calendar_create/update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the read scope ("within the period") but gives no when-to-use, no when-not, and no alternative tool. An agent gets no routing help against the calendar_source_get or resource_pool_catalog_list siblings, and must infer from the schema that id must be sourced elsewhere.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description largely restates that safety profile ("without changing anything", "never changed"). The scoping detail that the resource pool is untouched, and that coverage is reported per source calendar/year, adds some value beyond the annotations but not rich behavioral context.

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

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

Two short sentences with the read-only nature front-loaded, and the second sentence reinforces the guarantee before the payoff. Slightly redundant, since "without changing anything" and "never changed" make the same point twice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only getter with a full output schema, complete parameter documentation and covering annotations, the description is sufficient; an agent knows what it returns and that nothing is mutated. Only the routing versus sibling calendar tools is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional source parameter, including its HTTPS/path format and the default-to-program-language behavior. The description adds nothing about the parameter, so the schema-driven baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Reads the holiday source") and clarifies the returned content: which source calendars exist and which years they cover. It implicitly contrasts with the write-oriented sibling rillsoft_calendar_source_import, but never names that alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the read-before-import workflow is inferable from the name and the sibling import tool, but the description never states when to call this versus rillsoft_calendar_source_import or rillsoft_calendar_list. No exclusions or prerequisites are given.

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

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

Annotations flag destructiveHint=true, but the description goes well beyond that by disclosing the exact blast radius: whole-year replacement, hand-entered company holidays in that year are lost, years without source data are untouched. It also states what the response contains (days removed and created per year) and the transactional precondition.

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

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

Front-loads purpose, then behavior, then the guard parameter, then the return, then the precondition. Every sentence carries information an agent needs; no filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, nested-schema, open-world operation this is complete: annotations cover safety, the output schema covers return shape, and the description covers destruction scope, guard behavior, and the transaction requirement. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics for 'years' by framing it as the sole protection against the whole-year overwrite. It does not add syntax details (array vs {from,to}) beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair ('adopts the holidays of a source calendar into a pool calendar'), which is unambiguous against siblings like rillsoft_calendar_source_get (read) or rillsoft_calendar_create (create). An agent can identify this as the bulk-import operation 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a hard precondition ('Inside an open unit of work only') and identifies 'years' as the only guard against the overwrite, which tells the agent how to use the tool safely. It does not, however, name alternative tools or explicitly say when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds valuable scope detail: exception days are replaced only inside the named range while days outside stay as they are. This precisely bounds the destructive behavior in a way annotations cannot.

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

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

Three short, front-loaded sentences with the partial-update contract stated first and the precondition last. No wasted text, though the final fragmentary 'Inside an open unit of work only' is slightly clipped.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema, full schema coverage, and safety annotations present, the description only needs to add behavioral nuance, which it does via the range-replacement rule. It is essentially complete for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 10 parameters, setting the baseline at 3. The description reinforces the range-scoped behavior of exceptionDays and the partial-update contract, but adds no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('changes a calendar as a partial update') and resource, and clarifies the mutation is partial rather than full. It reads clearly against siblings like rillsoft_calendar_create and rillsoft_calendar_delete, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a real precondition ('inside an open unit of work only') and clarifies partial-update semantics so the agent knows omitted fields are untouched. It does not explicitly route between update/create/delete 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.

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

Annotations cover only the read/write/idempotency profile, but the description adds rich context the annotations cannot: immediate effect with no undo (history_undo does not take it back), the project is not marked as changed, refusal in an open portfolio, auth/license requirements, and that the response is the stored document.

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

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

The purpose and key constraint are front-loaded and nearly every clause carries operational value (undo behavior, prerequisite tools, restrictions). It is, however, a dense run-on paragraph that could be structured with clearer breaks to improve parseability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema and annotations present, the description covers prerequisites, side effects, restrictions, and return value, leaving nothing an agent would need in order to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description reinforces usage (task uuid needed, folderId from rillsoft_document_ris_list) but adds no syntax or format detail beyond what the schema provides, matching the baseline for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: stores a local file as a new DMS document on the Rillsoft Integration Server and attaches it to a task/subproject/project, explicitly likening it to the 'Add' button. This clearly distinguishes it from siblings like rillsoft_document_ris_update and rillsoft_document_ris_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use conditions and constraints: documents are accepted on tasks only today, subproject/project answers ris_not_found, so pass a task uuid. It also points to rillsoft_document_ris_delete for removal and states prerequisites (project stored, DMS license, create role).

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

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

Goes well beyond the destructiveHint=true annotation by disclosing that the delete is a soft delete (server deactivates it, admin can restore), that it takes effect immediately with no undo, that the project is not marked changed, that a missing document returns ris_not_found, and that it runs as the desktop session login requiring the delete role. This is exactly the operational detail annotations cannot carry.

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

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

Front-loads the core action, then layers side constraints, error behavior, counterpart tool, and auth requirement in compact clauses with no wasted sentences. Dense but efficient; slightly jammed into one paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. The description still covers the semantics an agent needs: soft-delete behavior, irreversibility, error case, permission requirement, and session context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and documentId is already documented as coming from rillsoft_document_ris_list. The description only adds the scoping notion 'of the open project', so per the high-coverage baseline a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (deletes) and resource (one document of the open project in the RIS document management), and anchors it to a concrete UI surface ('the Delete button of the documents page'). It also names its counterpart rillsoft_document_ris_create, so an agent can distinguish it from create/update/get/list siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this applies (deleting a document from the open project via the documents page) and points to rillsoft_document_ris_create as the counterpart operation. It does not explicitly enumerate when NOT to use it (e.g., folder_ris_delete vs document deletion), so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable beyond-annotation behavior: an existing file is refused unless overwrite:true, no partial file is left on failure, runs with desktop session login. Does not mention output schema contents, but those are declared.

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

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

Dense but front-loaded: purpose first, then overwrite rule, failure safety, and session context. Each sentence carries distinct information. Slightly long sentence but no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, id source, overwrite semantics, failure safety, session authentication, and 'no undo' irreversibility. With a rich schema (100% coverage) and output schema, the description provides everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters (path, overwrite, documentId) are fully documented in the schema. The description adds semantic context for path ('target path given instead of asked') and overwrite refusal behavior, but mostly reiterates schema content. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Downloads one document of the open project from the document management') and maps it to a concrete UI analogue ('the Download button of the documents page'). Clearly distinguishes from siblings by contrasting the target path being given instead of asked, and points to rillsoft_document_ris_list for ids.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: which document source, where ids come from (rillsoft_document_ris_list), and the overwrite behavior condition. Does not explicitly name when to prefer rillsoft_document_ris_update/create, but the download purpose is unambiguous against those siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world. The description adds real value beyond them: it reads the server every call, runs with the desktop session login, and has no undo step. It also explains the portfolio-vs-project output difference (portfolioId returned, projectId per project). It does not discuss auth failure modes or result size/pagination, keeping it from a 5.

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

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

Information-dense but long-winded, with heavy em-dash clauses and interleaved portfolio, download, prerequisite and output details. The core 'what it lists' is front-loaded, but the middle sentences ramble and could be tightened without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description needn't enumerate return fields, yet it usefully names the identifying fields (uuid, folderId, folderPath, documentId). With a single optional param, annotations, and output schema, the description covers the prerequisites and portfolio edge cases an agent needs; only failure/auth specifics are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema documents the uuid parameter fully. The description reinforces the semantics by explaining that omitting uuid returns every document, and that each returned document carries uuid/folderId/folderPath/documentId – meaningfully linking the parameter to the output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the documents the DMS... holds') and scopes it to the open project, including which elements documents hang on. Explicitly distinguishes itself from the sibling rillsoft_project_file_open and from the document create tool, so an agent can route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit prerequisites (project must be opened via rillsoft_project_ris_open or saved via rillsoft_project_ris_save_as; new/file-based projects have none) and states what is and isn't supported in a portfolio (read/update/delete work, create is refused). Names the sibling not to be confused with.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false): it explains that path replacement overwrites the stored file and renames the document to the new file's name, that changes apply server-side immediately with no undo, that the project is not marked as changed, that it runs under the desktop session login, and that the modify role is required. This is exactly the extra behavioral context the annotations cannot convey.

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

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

Front-loaded with the core action and the required-parameter constraint, and every clause carries real information (destructiveness, no undo, role requirement). It is dense and somewhat run-on, and the UI-action mapping (dragging, 'Upload' button) is slightly verbose, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. Combined with the schema, the description covers auth requirements, side effects (overwrite/no undo/rename), the no-op condition, and the immovable-parent constraint, leaving no material gap for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the per-field meanings are already documented (baseline 3). The description adds cross-parameter semantics the schema cannot express: the at-least-one-of constraint across description/folderId/path, and the consequence that replacing content via path also renames the document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Changes') and the exact resources touched (description, DMS folder, and/or document content) within the Rillsoft Integration Server document management. It maps the operation to concrete UI actions (edit in list, drag into folder, Upload button), which distinguishes it from rillsoft_document_ris_create/delete/get without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the precondition that at least one of description, folderId, or path is required, and rules out changing the parent element ('cannot be changed - delete and attach again'), plus the no-op case ('without a path and without a difference nothing is sent'). It does not name sibling tools as alternatives by name, but the when/when-not conditions are clear.

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

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

Annotations already mark this destructive and non-idempotent, and the description goes beyond that by disclosing cascade scope (dependencies / subproject content are removed with the element), the protected resource (main project cannot be deleted), and reversibility ('One undo step'). These are exactly the behavioral facts an agent needs before committing a destructive call.

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

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

The destructive scope and the protected-root constraint are front-loaded, and every sentence carries information. The third sentence ('Here element means a task or a subproject - this is the generic way that takes either') slightly restates what the opening sentence already implied, which is the only real redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. With cascade behavior, the undeletable project, the undo guarantee, and routing to the two kind-specific siblings all covered, an agent has everything needed to call this correctly and safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema already defines uuid as the task/subproject identifier and the description adds nothing further (no format, no way to obtain the UUID). Baseline 3 applies when the schema carries the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (deletes) and resource (task or subproject), and explicitly defines the ambiguous term 'element' so the agent knows the tool is the polymorphic variant. It also names the two sibling tools that handle single kinds, so an agent can distinguish this tool from rillsoft_task_delete and rillsoft_subproject_delete without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit selection rule: use this generic tool when the element kind is unknown, and use rillsoft_task_delete / rillsoft_subproject_delete when the kind is known ('they refuse the other kind'). It also states an exclusion — 'The main project cannot be deleted' — which prevents a whole class of failed calls.

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

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

Adds substantial behavioral context beyond the annotations: WBS codes are reassigned, dependencies and assignments survive, display rows split cleanly when partially moved, portfolio-level restrictions apply, direction can reorder projects at portfolio level, and the operation is one undo step. Annotations only give basic flags, so the description carries useful operational detail.

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

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

The description is front-loaded with the core purpose and parameter rule, then layered with behavioral details. It is appropriately sized for a complex move operation, though the abbreviation 'RP' is unexplained and a couple of clauses could be tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema, output schema, and annotations, the description covers the key behavioral constraints an agent needs: parameter combination rules, data preservation, undo behavior, display-row integrity, and portfolio limitations. Nothing critical appears missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents parameters in detail. The description still adds meaning by tying 'position' to 'newParentUuid', clarifying the role of 'direction' for portfolio-level project reordering, and explaining the element concept for uuid/uuids, though much of the combination logic is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Moves elements') and clarifies that an element is a task or subproject, which helps distinguish the resource. However, it does not explicitly differentiate from siblings like rillsoft_element_reorder, so an agent may still need to infer which move/reorder tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear parameter combination rules ('exactly one of position with newParentUuid, direction, or extractFromSubproject') and some portfolio context, but it does not state when to use this tool instead of alternatives such as rillsoft_element_reorder or rillsoft_element_subproject_group. Usage is largely implied.

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

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

It discloses behavior well beyond the annotations: WBS codes are reassigned, an order that separates a display row is refused and names affected UUIDs, dissolveRows can override that refusal, and the operation is a single undo step. These are concrete mutation and error-handling details an agent needs.

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

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

The description is front-loaded with the core action and packs important constraints into compact sentences. Every sentence contributes operational meaning without padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition covers what the tool does, its mutation behavior, refusal condition, override option, and undo semantics. With an output schema and annotations present, it is largely complete; the main missing element is explicit guidance on when to choose this tool over sibling reorder/move tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already documented. The description adds some useful context by defining what a 'child' is, but most parameter-level meaning is already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Reorders') and resource ('every direct child of a subproject'), then defines a child as a task or subproject. This is precise enough to distinguish it from more general element movement or project sorting tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the operation and its refusal behavior, but it does not say when to use this tool instead of alternatives such as rillsoft_element_move or rillsoft_project_sort. Usage is only implied by the tool's purpose.

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

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

Annotations already declare readOnly=false, destructive=false, and idempotent=false, so the safety profile is covered. The description adds genuinely new context: single-undo semantics that also remove the new subproject, and the portfolio-level restriction. It does not discuss permissions/auth, keeping it short of a 5.

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

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

Front-loads the core action, then the alternative, then constraints, undo, and return content. Every sentence carries information, though the prose is dense and slightly run-on, costing some readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema present, the description covers the alternative path, the portfolio precondition, undo behavior, and the shape of the response. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so uuid/uuids/name semantics are already documented in the schema. The description only restates that elements are named and adds that an element is a task or subproject, adding marginal value over the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific compound action (creates a subproject and pulls named elements into it) and defines 'element' as a task or subproject. It also names the sibling it is NOT (rillsoft_subproject_create for empty subprojects), so an agent can distinguish it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the empty-subproject case to rillsoft_subproject_create and states the portfolio-level precondition (elements must lie inside a project, since a portfolio-level subproject would be a project). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context beyond the annotations: 'Read-only, no undo step' clarifies there is no history entry, and the explanation of fixed elements' relationship to rescheduling provides domain-specific behavioral insight. However, it does not describe output shape or pagination, so a 4 is appropriate.

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

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

The description is four sentences and front-loads the core purpose before elaborating on rescheduling context and the read-only note. Every sentence adds value, though the projectFixed aside is slightly tangential. It remains tighter than most definitions without sacrificing necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has zero parameters, an output schema, and full annotations, the description is complete. It explains the domain concept, the tool's role in the rescheduling workflow, and safety behavior. Nothing an agent needs in order to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline score is 4. The description does not introduce any parameters and instead focuses on semantics and usage, which is correct for a parameterless tool. No additional parameter meaning is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Lists), resource (fixed element of the project), and defines the element types (task, milestone, subproject) whose dates are pinned. It explicitly distinguishes from sibling rillsoft_project_reschedule by describing the exact relationship between them. An agent can identify the tool's purpose without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative behavior (reschedule leaves fixed elements in place) and points to the tools needed to change state (rillsoft_task_update or rillsoft_subproject_update with fixed:false). The condition for using this tool is clear: to find fixed elements before attempting a free reschedule. It also notes the main project equivalent via projectFixed.

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

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

Goes well beyond the annotations: it discloses that the change is immediate with no undo step, names the inverse tool, states the pre-flight validation behavior for an unknown parent, and pins the auth context to the logged-in desktop session. Annotations (destructiveHint=false, idempotentHint=false) are consistent with a create that destroys nothing itself and is reversed by delete.

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

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

Purpose is front-loaded in the first clause, followed by effect, reversal, validation, and auth context — four compact sentences with no filler. Slightly dense but every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema, the description covers what it does, its side effects, reversal path, validation failure mode, and execution identity. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (name, parentFolderId) are documented in the schema, including the 'root folders cannot be created' constraint. The description adds no format, syntax, or naming-rule detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a subfolder in the project folder tree') plus the exact UI affordance it mirrors, so an agent can identify it against rillsoft_folder_ris_list/update/move. It explicitly names rillsoft_folder_ris_delete as the reversal path, sharpening the distinction from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating context: immediate server effect, reversal only through rillsoft_folder_ris_delete, and that an unknown parent is rejected pre-send. It stops short of explicit 'use X when Y' routing for the other folder siblings (list, update, move).

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

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

Annotations cover the safety profile (destructive=true, idempotent=true, openWorld=true), and the description adds real value beyond them: it is a soft delete (server deactivates the folder), there is no undo, it takes effect immediately, nothing is removed silently, and it runs under the desktop session login. It also surfaces the specific error code for the refusal case.

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

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

Front-loaded with the action and scope, and every clause carries information (UI mapping, refusal rule, soft-delete semantics, irreversibility, counterpart, auth context). It runs to six short clauses, which is a touch verbose, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers scope, precondition/refusal behavior, side effects, reversibility and execution context. An output schema exists so return values need not be described, and the annotations carry the safety hints, leaving nothing an agent needs missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single folderId parameter is already documented with its origin (rillsoft_folder_ris_list). The description adds no syntax, format or constraint detail about the parameter, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Deletes an empty project folder ... on the Rillsoft Integration Server') with scope (logged-in client, empty folders only). It also names the sibling counterpart (rillsoft_folder_ris_create), so it is distinguishable from the other delete tools in the family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-not condition: a folder holding subfolders or projects is refused with ris_folder_not_empty. It names the counterpart tool rillsoft_folder_ris_create and points at rillsoft_folder_ris_list as the source of folderId, giving the agent clear routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description still adds genuine context: it runs under the desktop session login, corresponds to a specific dialog, and restates that there is no undo step. It stops short of describing pagination or tree-size limits, so not a 5.

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

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

Front-loaded with purpose, then exclusions, then auth/behavior — a sensible order with little waste. 'Read-only, no undo step' partially duplicates the annotations, which keeps it from being maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present it needn't explain return values, and it doesn't over-explain them. Purpose, routing to the correct sibling, the consuming tools, and the auth/session context are all present, leaving nothing an agent needs before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'permission' enum is fully documented in the schema (default project_read, meaning of each value). The description says nothing further about the parameter, so the baseline 3 for schema-does-the-work applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the project folder tree'), identifies the concrete UI surface ('the tree of the Open from database dialog'), and lists the returned fields (parentFolderId, path, depth). It also names the sibling it is NOT (rillsoft_document_ris_list) so the agent can distinguish it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit exclusion ('Not the DMS folder tree of the documents (rillsoft_document_ris_list)') and states the downstream consumers of the output, naming rillsoft_project_ris_save_as and 'the other folder tools'. That covers both when to use it and where its output flows, which is exactly what routes an agent correctly.

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

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

Annotations already declare write/idempotent/non-destructive, and the description adds real behavioral context: 'Takes effect at once: no undo step', the cycle restriction, and that it runs under the desktop session login. It stops short of describing server-side error behavior or side effects on contained projects beyond the move itself.

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

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

Front-loads the core action, and each clause carries information (scope, alternative tools, constraint, immediacy, session). The 'dragging in the folder dialog, plus the sibling positions the server offers' fragment is slightly loose, but overall it is efficient rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, 100% param coverage, and rich annotations, the description only needs to add routing and behavioral caveats — which it does, including the no-undo warning and the clone/cycle rule. 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so folderId, targetFolderId, and the position enum are already fully documented. The description gestures at the semantics ('under another folder or next to it', 'the sibling positions the server offers') but adds little beyond the schema's own worst-case detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a specific verb+resource ('Moves a project folder ... on the Rillsoft Integration Server') and clarifies the scope (with subfolders and projects, under or next to a target). It actively distinguishes itself from siblings by naming rillsoft_folder_ris_update for renaming and rillsoft_project_ris_save_as for changing a project's folder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: renaming belongs to rillsoft_folder_ris_update, and moving a project to another folder belongs to rillsoft_project_ris_save_as. It also states the condition that selects this tool (reparenting/reordering a folder) and the constraint case (ris_folder_cycle).

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

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

Adds real behavioral facts beyond the annotations: changes take effect on the server immediately, there is no undo step, and the call runs under the desktop session login (auth context). The idempotency note ('the same name again sends nothing') usefully reinforces idempotentHint=true. It omits error/edge-case behavior for a rename, which keeps it short of a 5.

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

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

Front-loaded with the verb and resource, then a sequence of short, information-dense sentences covering the no-op case, the alternative tool, permanence, and auth. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. For a two-parameter rename with a fully documented schema, the description supplies everything an agent needs: scope, permanence, idempotency, the sibling to use for moving, and the auth context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% ('new name', 'id of the folder, from rillsoft_folder_ris_list'), so the schema already carries parameter meaning. The description adds only the framing that this edits the folder's label; no additional format or constraint detail. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (renames a project folder on the Rillsoft Integration Server) plus scope (logged-in client) and clarifies it is a label edit, not a general update. It explicitly disambiguates from the closest sibling ('Moving a folder is rillsoft_folder_ris_move'), so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete alternative for the ambiguous case by naming rillsoft_folder_ris_move, and notes that re-sending the same name is a no-op. It does not explicitly say when to use this vs. folder_ris_create/delete/list, but those are unambiguous from the verb.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false; the description usefully explains the rationale ('restores the step and takes nothing away') and that the redone command is reported. It does not address the non-idempotent hint or how the redo stack behaves, so it adds moderate rather than rich context.

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

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

Three short sentences, front-loaded with the action and immediately followed by the sibling relationship. The trailing fragment 'One undo step.' is terse but earns its place by bounding the scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema covering the returned command and annotations covering the safety profile, the description only needs purpose and counterpart context, both of which it supplies. Remaining gaps (redo-stack state, empty-stack behavior) are minor for a zero-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Its scope note 'One undo step' correctly signals that no step identifier or count is accepted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Redoes') plus the exact resource ('the undo step taken back last') and names the sibling it is the counterpart of, rillsoft_history_undo. An agent can distinguish this from the undo tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames itself as the counterpart to rillsoft_history_undo, which tells the agent it is the reverse operation used after an undo. It does not state any exclusion (e.g. what happens when the redo stack is empty), so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds genuine context beyond that: it reports the undone command, scopes the operation to the open project's history, and discloses boundary behavior for saves and the resource pool.

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

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

Three compact sentences, front-loaded with the core action and then the boundaries. Mostly efficient, though 'including changes made in the user interface' is slightly opaque and adds little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and there are no parameters to document. The description covers scope and edge cases well; only the minor opening ambiguity keeps it from full marks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. There is no parameter surface for the description to clarify or obscure, and 'One undo step' usefully signals that a single call performs exactly one step.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (undo the last command in the open project's history) and explicitly distinguishes itself from the redo sibling and from save-undo. The opening phrase 'Undoes the last undo step' is mildly ambiguous (it could read as a redo), but the following sentences resolve it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use (walks the command history of the open project), when-not (not a way to undo a save; the resource pool has no undo step and instead closes the unit of work without saving), and names the alternative path (rillsoft_history_redo). Nothing is left to inference.

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

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

Annotations already mark the tool as destructive and idempotent, but the description adds substantial behavioral detail: information loss, the shared value being the maximum over participants, the non-inverse relationship with release, the move of the resource from machineAssignments to sharedAssignments, and the single undo step. This is exactly the kind of context annotations cannot convey.

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

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

The description is dense but front-loaded, leading with the core operation before the caveats. Every sentence carries useful information, though it is longer than strictly necessary and could be tightened slightly without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values. It fully covers side effects, constraints, reversibility, and post-condition state changes, leaving an agent well equipped to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the constraint that each task must already carry the resource and that the type is limited to machine or machine_role, but adds little syntax or format detail beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Lets several tasks share one machine or machine role') and immediately distinguishes the operation from sibling tools like rillsoft_machine_sharing_release. An agent can identify exactly what this tool does 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for use ('several tasks share one machine') and constraints such as 'each of them has to carry it on its own today' and 'all tasks must belong to the same project.' It also warns that rillsoft_machine_sharing_release is not the inverse, which helps prevent misuse. It lacks an explicit when-not or alternative tool recommendation beyond that contrast.

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

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

Annotations already declare destructive=true, idempotent=true and readOnly=false, so the safety profile is covered. The description adds genuinely non-obvious semantics beyond that: the task regains its individual assignment but carries the shared value rather than its original one, and the shared entry vanishes once the last task is released. That 'original value is not restored' nuance is exactly the kind of context annotations cannot convey.

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

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

Three tight clauses, front-loaded with the core action and the resulting state before the sibling reference and undo note. No filler, though the parenthetical cross-reference and menu-name aside are slight extras.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers outcome, side effect on the shared entry, reversibility, and the sibling relationship. The only gap is error/edge behavior when the task is not currently in shared use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented in the schema and the baseline is 3. The description hints at the single-task scope ('one task', 'the shared entry') but adds no format or enum detail beyond what the schema supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Takes one task back out of shared use') and immediately gives the resulting state, distinguishing it from the create counterpart by name. An agent can tell exactly what this does and which sibling mirrors it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names rillsoft_machine_sharing_create as the counterpart and frames this as the 'Exclusive' menu entry's opposite plus a single undo step, which tells the agent when this tool applies. It stops short of stating when NOT to use it (e.g., what happens if the task is not currently shared).

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

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

Goes well beyond the annotations by resolving their apparent tension: it explains why a tool that mutates stored display state counts as read-only (no undo step, no task/assignment/date changes) and warns that the outline state persists with the project and a later save writes it along. It also flags non-repeatability of step_expand/step_collapse due to view-dependent state, matching idempotentHint=false.

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

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

Front-loads the core effect in the first sentence before the exclusivity rule and the behavioral caveats. It is dense and slightly long, and the 'that is why this tool counts as read-only' clause retreads the readOnlyHint, but each sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, oneOf-constrained tool with an output schema and full annotation coverage, the description supplies everything an agent needs: the exclusivity rule, the failure mode on wrong views, the persistence side effect, and a pointer to the analogous get tool for the response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents the enum values and exclusivity, so baseline is 3. The description adds the rationale the schema lacks: openRows exists specifically to replay a state read beforehand when rows were opened by hand, and the two step values move one step rather than to an absolute state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('expands or collapses the visible resource or capacity view') and grounds it in a concrete UI analogue ('the same effect as the expand and collapse buttons of the ribbon'). It distinguishes itself from siblings by naming rillsoft_view_state_apply as the tool for other views, and 'answers like rillsoft_outline_get' ties it to its read counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit mutual exclusion ('Give exactly one of outline and openRows') plus the condition that selects openRows over outline ('restores a state read before, row by row, which outline alone cannot do'). It also names the fallback tool and the failure condition ('In any other view the call fails and points at rillsoft_view_state_apply'), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered; 'Read-only, no undo step' is largely redundant. The real added value is the disclosed failure mode (call fails in views other than the visible resource/capacity view) and the error-routing to rillsoft_view_state_apply, which annotations do not convey.

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

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

Purpose is front-loaded, but the long colon-delimited run-on enumerating outline/openRows/levels/canExpand/canCollapse restates what the output schema already documents, so several clauses do not earn their place. The key operational fact (failure in other views) is buried at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering safety, an output schema covering return values, and no parameters, the description only needs to frame the tool and its constraints. It does so, adding the view-scoped failure behavior and the correct fallback sibling, so it is essentially complete aside from not routing to outline_apply.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description goes further by naming the returned fields, but that duplicates the output schema rather than clarifying any input semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Reads how far the visible resource or capacity view is expanded') and enumerates the exact output fields (outline, openRows[], levels[], canExpand, canCollapse). This is clearly a read of outline state, but it never explicitly contrasts itself with the closest siblings (rillsoft_outline_apply / rillsoft_outline_row_apply), leaving that inference to the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit when-not condition: in any other view the call fails and routes the agent to rillsoft_view_state_apply. That names an alternative and the condition that selects it. It does not, however, spell out the read-vs-apply workflow with outline_apply, so guidance is strong but not exhaustive.

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

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

Goes well beyond the annotations: it explains why readOnlyHint=true is not contradictory (no task/assignment/date changes, no undo step) while still disclosing the side effect that outline state is persisted with the project and marks the document as changed, so a later save writes it. It also confirms idempotency behavior and notes the selection and property sheet follow, like a click.

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

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

Front-loaded with the core action and the sibling differentiation, and nearly every sentence carries information. It is on the long side, with some restatement around the read-only rationale ('no task, no assignment, no date moves'), which costs a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, nested-object tool with an output schema and full annotation coverage, the description covers behavior, prerequisites, side effects, failure routing and return shape reference ('answers like rillsoft_outline_get'). Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the nested row object documents every coordinate field, so the baseline is 3. The description adds contextual meaning about addressability (parent must be open) but no new syntax or format detail for the parameters themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: opens or closes one single group row of the visible resource or capacity view, equivalent to clicking the plus/minus. It explicitly contrasts itself with rillsoft_outline_apply, so the agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (single row vs rillsoft_outline_apply's whole-outline effect), prerequisites (a row whose parent is closed is not addressable; open the parent first), and a failure route (other views fail and point at rillsoft_view_state_apply). Nothing is left to inference.

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

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

Annotations already flag destructiveHint/readOnlyHint, but the description adds substantive behavior: the current project is replaced wholesale, the .rpp is refused if it is a single project, there is no undo, and inside a portfolio no creation below the portfolio, no cross-boundary dependencies, no baseline and no 'save as' are permitted. This is well beyond what annotations convey.

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

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

The core action and the sibling split are front-loaded in the first two sentences, and the remaining sentences each carry a distinct constraint. It is dense and long, but little of it is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, state-replacing open operation, the description covers refusal behavior, the no-undo consequence, portfolio-specific limits, and the follow-up save tool. Return fields (portfolio:true, projects[], skipped[], note) are restated even though an output schema exists, but the coverage is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented in the schema; the description only implies that path must point at an .rpp rather than an .rpj. Baseline 3 applies when the schema carries the parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Opens exactly one file portfolio (.rpp)') plus the scope caveat that it 'replaces the current project'. It explicitly distinguishes itself from rillsoft_project_file_open by noting that a .rpj is refused and that the sibling covers it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not rule (.rpj is refused, use rillsoft_project_file_open) and names the companion write path (rillsoft_portfolio_project_files_save). It also warns 'No undo step', which directly shapes call decisions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: only locked, writable members are saved, the list file is untouched, and there is 'No undo step.' The saved[] naming and refusal conditions are useful. It stops short of describing partial-failure behavior or how writability/lock state is determined, so it is not exhaustive.

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

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

The core action is front-loaded in the opening clause, and every sentence carries information: scope, refusal condition, alternative, and undo behavior. It is dense with semicolons and em-dashes but not padded with filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and with zero parameters there is no input surface to document. Combined with annotations covering the destructive/idempotent profile, the description covers the refusal case, the scoping rule, and the lack of undo — everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4 and the description does not need to explain inputs. It redirects its detail to output/behavior semantics (saved[] naming) rather than parameter guidance, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Writes the projects of an open file portfolio back into their own .rpj files') and immediately scopes it against siblings by declaring that the .rpp itself is never written and there is no 'save as' for it. An agent can distinguish this from rillsoft_project_file_save and rillsoft_portfolio_ris_save without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the negative case ('Where a single project is open, the call is refused') and names the exact alternative to use instead ('use rillsoft_project_file_save'). Both the when and the when-not are spelled out with a concrete route.

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

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

Annotations only declare the write/openWorld/idempotent profile; the description adds the important traits: it takes effect on the server immediately with no undo step, it runs under the desktop session login, and duplicate names or unknown folder/project ids are refused before anything is sent. This is substantially more than the annotations convey and consistent with them (destructive=false since it only adds a portfolio).

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

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

Front-loaded with the verb and resource, then effect, alternatives, and validation in a compact block. Slightly dense with multiple clauses in one sentence, but every clause adds usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and the description covers the remaining agent-relevant questions: immediacy, reversibility, authorisation context, validation failures, and related tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already documented; the description only loosely restates 'its kind, folders and projects' without adding format or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (creates) and resource (portfolio of the logged-in client on the RIS), and anchors it to a known UI affordance (the 'New' button of the portfolio dialog). It also names sibling tools (delete/open) so the agent can place it in the portfolio lifecycle without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context for when this applies and what the natural follow-ups are: rillsoft_portfolio_ris_delete removes it and rillsoft_portfolio_ris_open loads it. It stops short of explicit exclusions (e.g., when to prefer update vs create), so it is strong context rather than full when/when-not routing.

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

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

Adds substantial behavior beyond the annotations: it discloses that the delete is a soft delete (record deactivated, projects untouched), that it takes effect immediately with no undo, that an open portfolio is refused, and that it runs under the desktop session login. These are exactly the side-effect and precondition details an agent cannot infer from destructiveHint/idempotentHint alone.

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

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

Front-loaded with the core action, then proceeds through side effects, refusal condition, reversibility, and session context. Every sentence contributes distinct information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive single-parameter mutation with an output schema present, the description covers side effects, refusal behavior, reversibility, and execution context. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single parameter already documented as 'id of the portfolio, from rillsoft_portfolio_ris_list'. The description adds no additional parameter syntax or format detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Deletes a portfolio of the logged-in client on the Rillsoft Integration Server') and identifies the exact UI affordance it mirrors. It also names the counterpart tool (rillsoft_portfolio_ris_create), so an agent can distinguish it from sibling mutations without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear precondition (refused when the portfolio is open, with the portfolio_is_open error) and points to the counterpart create tool, giving real when-to-use context. The remediation hint 'call rillsoft_project_create first' is confusing and possibly incorrect for an open-portfolio state, which keeps it from a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), and the description adds genuinely useful context beyond them: it runs under the desktop session login, never prompts for credentials, and returns server/userName/clientId. It also re-states read-only/no-undo, which is redundant with annotations but harmless.

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

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

Purpose and scope are front-loaded, followed by the sibling routing and then the auth/return behavior. Slightly dense with clauses, but every sentence carries information relevant to calling or interpreting the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure need not be explained, yet the description helpfully names key response fields. Combined with sibling routing and auth behavior, an agent has what it needs; only explicit exclusion conditions are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'combine' enum parameter is fully documented in the schema itself, including the meaning of all, portfolio, and combine. The description adds no syntax or semantics for the parameter, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (lists the logged-in client's RIS portfolios, both project portfolios and summary projects) and explicitly distinguishes itself from the sibling rillsoft_portfolio_ris_open (which consumes the returned portfolioId) and rillsoft_portfolio_file_open (which opens .rpp files). An agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when to use it: to obtain portfolios plus the portfolioId that rillsoft_portfolio_ris_open requires, and explicitly names the alternative path for opening .rpp portfolio files. It does not state explicit exclusions (e.g. when not to call it or prerequisite session state), but the routing guidance is concrete.

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

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

Goes well beyond the annotations: it discloses that the current document is replaced, the UI-imposed limits (nothing directly below the portfolio, cross-project dependencies become RIS links, no baseline, no 'save as'), which operations work on loaded project documents (list/download/update/delete, not create), that unreadable/foreign-pool projects are omitted and named in 'skipped', the discardChanges requirement, and that there is no undo because command history restarts. Matches the destructiveHint=true / idempotentHint=true annotations.

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

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

Front-loaded with the core action, then dense but information-bearing caveats. The long parenthetical is heavy but each clause (limits, skipped projects, discardChanges, save path, undo) earns its place; only minor tightening is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex state-mutating tool with an output schema already present, the description covers side effects, limits, locking implications, skip behavior, the discardChanges prerequisite, redirects to the correct sibling tools, and the loss of undo. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents lock, projectIds, discardChanges and readOnlyProjectIds. The description reinforces discardChanges:true behavior and references 'skipped', but adds little semantic detail beyond what the parameter descriptions already carry; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Opens) and resource (portfolio of the logged-in client from the Rillsoft Integration Server), and explicitly distinguishes itself from siblings rillsoft_portfolio_file_open (opens a file) and rillsoft_portfolio_ris_save (saving). An agent can tell exactly what this does and how it differs from adjacent tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternatives and when they apply ('Saving goes back through rillsoft_portfolio_ris_save; a portfolio file is opened through rillsoft_portfolio_file_open instead') and gives the condition for discardChanges:true. Clear context, though it stops short of an explicit 'use this when / not when' framing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: versioning semantics (each changed project gets a new version), that links/configuration/favourites/signature are written, that the portfolio is reloaded while preserving display state, that it runs under the desktop session login, and critically that there is no undo step. It also names failure conditions (link cycle stops the save; refused when the open document is not a server portfolio).

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

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

The core write semantics and the alternative-tool routing are front-loaded, and most clauses carry real information (failures, no-undo, session context). It is dense and long for one tool, with some run-on sentences, but little is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return formatting need not be explained, and annotations cover the safety profile. Given a single optional parameter, the description supplies the remaining essentials: precondition (open server portfolio), side effects and permanence, no-op behavior, error codes, and side conditions like link cycles.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema description coverage is 100%, so the schema fully documents `notes` including the 2000-character limit. The description references 'a note' and a cycle 'named in note', which are return/status messages rather than the parameter, so it adds no semantics for `notes` itself. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('writes the open portfolio of the Rillsoft Integration Server back'), enumerates what is written (changed non-read-only projects, links, configuration, favourites, signature) and explicitly names the sibling tools it is not (rillsoft_project_ris_save, rillsoft_portfolio_project_files_save). An agent can distinguish it from adjacent save tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit preconditions (an open portfolio of the server, otherwise ris_portfolio_not_open) and routes to the correct alternative for each non-matching case: single project via rillsoft_project_ris_save, portfolio file via rillsoft_portfolio_project_files_save. Also states the no-op case ('nothing changed means nothing written'), so when-to-use and when-not are both covered.

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

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

Adds context beyond the annotations: changes take effect on the server immediately with no undo step, open portfolios see the change only on the next rillsoft_portfolio_ris_open, and the call runs with the desktop-session login. These are the operational facts an agent needs before a mutation, and they do not contradict destructiveHint=false or idempotentHint=true.

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

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

Dense but front-loaded: the rename/replace purpose comes first, then constraints, then side effects. The mention of the desktop UI dialogs is slightly padded for an agent audience but negligible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter update tool with full schema coverage, an output schema, and safety annotations, the description covers everything material: required inputs, immutability of kind, immediacy/no-undo, visibility timing for open portfolios, and session context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds the cross-parameter constraint (at least one of name/folderIds/projectIds) which the schema does not express, but otherwise restates what the schema already documents about replacement semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (renames / replaces selection) and resource (portfolio of the logged-in client on the Rillsoft Integration Server), and explicitly carves out what cannot be changed (the kind). It is distinguishable from siblings such as rillsoft_portfolio_ris_create/list/delete without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'at least one of name, folderIds and projectIds is required' and that the kind cannot be changed, which rules out misuse. It stops short of naming which sibling to use when the kind must change or when the operation should be an open/save instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real behavioral context beyond that: one task can appear in several lists (no deduplication), units are hours, dates follow the project convention, and there is no undo step. These are the kind of traits an agent cannot infer from annotations alone.

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

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

The purpose is front-loaded and the trailing sentences are short and information-dense. The six-category enumeration makes the single sentence long, but each item earns its place by defining a selectable category, so it is informative rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure need not be described. Given a single optional enum parameter, the description covers scope, category semantics, overlap behavior, units, and read-only status — 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the enum is self-documenting, so the baseline would be 3. The description goes further by explaining what each category actually means ('delayed (tasks lagging behind the status date)', 'overload (overallocated resources)', 'crossProjectDependencies ... together with their float'), which is semantic value the enum labels alone do not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Reads the six conflict lists of the info sheet as a flat YAML report') and then enumerates all six categories with a one-phrase gloss for each. This distinguishes it cleanly from sibling report tools such as rillsoft_analysis_report_get and rillsoft_variance_report_get without the agent needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'The same selection as the tabs of that sheet' tells the agent the categories correspond to UI tabs, and the schema says to omit 'category' for all lists. But there is no explicit when-to-use guidance versus the other reporting siblings (variance_report_get, analysis_report_get, resource_usage_list), nor any stated preconditions.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: it replaces the currently open project, discards unsaved changes when required, resets the command history, and cannot be undone. These consequences are exactly what an agent needs before invoking a destructive tool.

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

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

Three tight sentences, front-loaded with the primary action and consequence. Every sentence carries distinct, non-redundant information (scope, parameter condition, alternative tool, irreversibility).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained. Given the tool's destructive nature, the description covers reversibility, side effects on the open project, the parameter condition, and the alternative tool, leaving no meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters (baseline 3). The description adds real semantic value by stating the condition under which discardChanges must be true, which the schema's terse 'true = discard unsaved changes' does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Creates a new empty project') and clarifies the scope by noting it 'replaces the one that is open.' It also distinguishes itself from the sibling rillsoft_project_file_open, which covers the different task of opening an existing file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit conditional guidance ('With unsaved changes pending, discardChanges:true is required') and names the correct alternative tool for a related-but-distinct task ('Opening an existing file goes through rillsoft_project_file_open'). The agent knows both when to use this and when to route elsewhere.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, and the description is consistent with them. It adds genuinely useful behavior beyond the annotations: exact output format/encoding, that the project path and saved state are untouched, that portfolios are refused, and that there is no undo step. It stops short of 5 only because it says nothing about permissions or failure modes.

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

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

Front-loaded with the core action, then the format, then the constraints. Every sentence carries information, though the parenthetical format details make the opening sentence dense. Still tight and purposeful overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description need not explain return values, and the rich annotations carry the safety profile. Given that, the description covers format, overwrite condition, non-mutation of the project, portfolio refusal, and no-undo, leaving nothing an agent needs in order to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines both parameters, making 3 the baseline. The description adds meaning beyond the schema by specifying that overwrite:true is required when the file already exists, which clarifies the consequence of omitting it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (writes the open project into an .xml file) plus the exact target format (rillprj version 13, UTF-8, RIS upload form). It also explicitly distinguishes itself from the older File-menu 'save as XML', so an agent can tell it apart from the other save/ris_save siblings without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real usage context: overwrite:true is required when the target exists, and a portfolio is refused. It also contrasts the tool with the alternative File-menu save, but it does not explicitly route against the many sibling save tools (project_file_save_as, project_ris_save_as, portfolio_project_files_save), so it stops short of full when-to-use/alternative guidance.

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

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

Beyond annotations (destructiveHint=true, idempotentHint=true), it discloses what actually gets destroyed ('replaces the current project'), the irreversible consequence ('No undo step - the command history starts over'), and the required flag under pending unsaved changes. This is exactly the extra context annotations cannot carry.

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

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

Four dense sentences, each load-bearing, with the destructive replacement front-loaded. The closing sentence about 'note' is the one arguable redundancy since an output schema exists, but it is short and orients the caller.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.