FMEPM Connect for Oracle EPM

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds valuable behavioral context by listing the returned information and diagnostic use cases, though it does not describe response structure or pagination behavior.

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

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

It is only two sentences and front-loads the returned contents before giving usage guidance. The long enumeration in the first sentence is functional because each listed item clarifies the tool's 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?

For a parameterless informational tool with no output schema, the description explains both what is returned and when to call it. Combined with the rich annotations, it gives the agent enough information 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?

The tool has zero parameters, so the baseline is 4. There is no parameter semantics to explain and no schema gap for the description to compensate for.

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

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

The description uses a specific verb, "Returns," and enumerates the exact resources: plan limits, usage, available tools, profile, connector version/build, and portal links. This makes it clearly distinguishable from siblings such as list_applications, get_api_version, and get_effective_policy.

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 triggering scenarios: asking what the connector can do, which plan is active, why a tool is missing, or what Oracle added recently. It does not explicitly state when not to use it or name an alternative, so it stops short of the top score.

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 real value beyond that by enumerating the status code semantics (Processing -1, Completed 0, Error 1, Cancelled 2) and noting that Oracle's details text is returned, which helps an agent interpret results.

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

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

Two sentences, front-loaded with the return-value semantics followed by the usage context. No filler, every clause carries information an agent needs.

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

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

With no output schema, the description carries the burden of describing return values, and it does so reasonably by listing status codes and the details text. It lacks guidance on polling cadence or whether status is eventually consistent, which is a minor gap for a status-check tool with full safety annotations.

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%, with jobId, appName, and connection all documented in the schema itself, including defaults. The description only implicitly references jobId via 'a job in the connected application' and adds no format or syntax detail beyond the schema, so 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?

Names a specific verb and resource ('Returns the status of a job') and enumerates the exact status codes with their numeric values. This distinguishes it cleanly from sibling tools like run_business_rule, which it explicitly cross-references.

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 says when to invoke it ('Use it after run_business_rule or any job submission to see whether the job finished'), which is a clear usage trigger. It stops short of stating exclusions or naming alternative polling/status mechanisms, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them — that it takes and stores no credentials and that authentication happens out-of-band in the portal — which is meaningful for an agent reasoning about a connect flow.

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

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

Three sentences, front-loaded with the return value and the connection options, then the security constraint, then the usage conditions. No filler and 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 zero-parameter, non-destructive read with no output schema, the description covers purpose, return value, security expectations, and triggers. Minor gap: it does not clarify how this relates to its closest sibling use_demo_environment, which also concerns sample-data connections.

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 there is nothing to disambiguate; the description correctly reinforces this by stating the tool takes no credentials. The baseline for no-param tools applies and no parameter detail is missing.

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 ('connect an EPM environment') and what the tool actually returns ('the link to the connect portal'), plus the three connection paths it describes. An agent can distinguish it from list_connections or use_demo_environment because the description positions it as the zero-input guidance/portal-link tool.

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

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

Explicitly names the three triggering conditions: no connection yet, wanting another one, or fixing a failing one. It also pre-empts the wrong expectation by saying credentials are entered in the portal, not here, which routes the agent away from trying to collect secrets.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description goes well beyond them: it discloses the policy cell-limit truncation with a note, the top-member/leaf-member data-availability trap, the caching behavior that 'fresh' overrides, and the planningData form-engine caveat where a parent in the POV returns nothing. These are non-obvious behavioral traits an agent could not infer from structured fields.

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?

It is one long paragraph, but the core purpose and default behavior are front-loaded and nearly every clause conveys operational information (mapping rules, empty-slice recovery, cell-limit note). A little denser than ideal — splitting the empty-result recovery advice out would read better.

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?

13 parameters, zero required, nested POV object, no output schema — the description compensates fully: it describes the return shape (table plus structured data, truncated with a note, per-dimension member report) and covers the main failure mode. Nothing material is missing for a correct invocation.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra by explaining the POV fallback-to-top-member rule, the requirement for leaf members on Scenario/Version/Currency, and worked examples like pov: { Version: "NSP_Base", Currency: "USD" } that show how dimensions map regardless of naming.

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 ('Exports a slice of numbers from any cube') and then details exactly what the slice consists of — rows/columns defaults, scenario/year/entity mapping to cube-specific names, other dimensions at top member. An agent can tell this apart from point_of_view or run_business_rule without reading 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 clear use case ('read actuals, plan or forecast numbers for analysis or commentary') and actionable guidance for the empty-result case (pass members or browse with list_dimension_members). It does not explicitly contrast itself with the sibling point_of_view or remembered_results tools, so routing among those is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful context beyond that by explaining it returns supported API versions and can serve as a connection check.

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 tightly written sentences, front-loaded with the return value and followed by the primary use case. No unnecessary text.

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

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

For a simple read-only version-check tool with rich annotations and fully documented schema, the description covers what it returns, an example value, and why an agent would call it. No output schema is needed given the clear return description.

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 optional connection parameter is already fully documented in the schema. The description does not add parameter-specific semantics beyond referring to the connected environment, so 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: returns the REST API versions supported by the connected Oracle EPM environment, with an example output (v3). This clearly distinguishes it from connection-management and job-status 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 usage context: use it to confirm a connection works before making other calls. It does not name explicit alternatives or exclusions, but the intended timing 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description goes beyond that by disclosing the composition semantics — the result is a merge of baseline, plan policy, tenant policy, person's profile, guidance level, plus tenant guidance text — which tells the agent the output is derived, not stored, and will change as those layers change.

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

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

Two sentences, front-loaded with what is returned, then why it exists. The long enumeration of policy facets is not padding — it substitutes for the absent output schema, so every clause earns its place.

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

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

There is no output schema, and the description compensates by listing the returned facets and explaining how they are assembled from the policy layers. Combined with the annotations, an agent has everything needed to call it with no arguments and interpret the result.

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 with an empty schema, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description correctly implies the tool is implicitly scoped to the calling user and plan rather than accepting selectors.

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 concrete verb+resource ('returns the policy in force for this user and plan') and then enumerates exactly what the policy covers (tools, applications, environments, business rules, limits, time window). No sibling tool in the list returns policy, so it is unambiguously distinguishable from about_connector, list_applications, or point_of_view.

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 two explicit triggering scenarios: explaining why a call was refused and checking what is allowed before proposing a change. It never names an alternative tool or a when-not condition, but the usage context is concrete enough that an agent knows when to reach for 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful domain context: that these variables control period, year, scenario and version, which tells the agent why the read matters and what the returned values mean.

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, zero filler, with the core read operation front-loaded and the usage cue placed last. Every sentence contributes 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?

With no output schema, the description correctly compensates by explaining what comes back: variable names, values and plan type scope. The only omission is whether results are paginated or filtered, which is minor for a small read-only lookup.

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%, with both appName and connection documented including their defaults, so the schema carries the parameter burden. The description adds no syntax or format detail for either parameter, making the baseline 3 appropriate.

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

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

States a specific verb and resource: 'Reads all substitution variables of an application,' and illustrates with concrete examples (CurrMonth, CurrYear) plus scope (values and plan type scope). It does not name the sibling update_substitution_variable outright, but the phrase 'before changing one' clearly separates it from the mutation 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?

'Use it before changing one or when a form or rule depends on one' gives two concrete triggering conditions, which is stronger than implied usage. It stops short of naming the alternative tool or stating explicit exclusions, so it falls below 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description only adds that each application's type and settings are returned; it says nothing about result size, pagination, or what happens when the connection has no applications. With annotations carrying the main burden, a 3 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?

Two short sentences, front-loaded with what is listed and followed by the usage hint. No filler, though the second sentence could have been used to add sibling routing rather than a soft usage note.

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

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

For a simple, read-only, single-optional-parameter list tool with full annotation coverage and complete schema descriptions, the description covers what it returns and why an agent would call it. Only minor gaps remain (empty-connection behavior, result scope).

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 'connection' parameter already documents that it can be an id or label from list_connections and defaults to the user's default connection. The description adds no parameter-level information, 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 ('Lists the applications in the connected Oracle EPM environment') and names what is returned ('type and settings'). It does not contrast itself with siblings like list_connections, so it falls 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?

'Use it to find the application name other tools need' gives a concrete usage context, which is more than nothing. However, there are no exclusions, no prerequisites, and no explicit pointer to the alternative tools that consume the returned name (e.g. run_business_rule, export_data_slice).

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, openWorldHint=false, and destructiveHint=false. The description adds substantial behavioral context beyond that: scoping to the user's own and shared connections, the environment override precedence, the fact that hosted applications reflect the last test, and multi-connection naming expectations. There is no contradiction with annotations.

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

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

The description is front-loaded with 'Lists the Oracle EPM connections' and then efficiently covers return fields and usage guidance. Despite being dense, every sentence adds useful information for selecting and 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?

With no output schema, the description appropriately explains the important return fields (id, label, environment, default application, hosted applications, auth type, status, default flag). For a zero-parameter, read-only listing tool with annotations already covering safety, this is complete enough to call correctly.

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

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

The tool has zero parameters, so there is no parameter semantics to document and the baseline score is 4. The description does not need to compensate for missing parameter 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?

The description gives a precise verb and resource: it lists Oracle EPM connections, states the scope (the user's own plus tenant-shared ones), and enumerates the returned fields. An agent can distinguish this listing tool from siblings like connect_epm_environment without opening any schema.

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

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

It explicitly says to use this tool to choose the connection argument for other tools or to verify that a connection exists before calling Oracle. It also gives multi-connection guidance about naming the connection in every call. It does not name explicit alternatives or when-not-to-use conditions, 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 declare readOnlyHint=true and destructiveHint=false, yet the description says the tool 'sets or clears' state that 'carries over between the user's requests on a connection.' Setting or clearing persistent state is a mutation, so an agent trusting the read-only annotation could call action=set or clear expecting no side effects. Side-effect semantics that matter this much are stated in contradiction to the structured safety metadata.

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

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

Two sentences, front-loaded with what the tool does, followed by the usage triggers; there is no filler. The first sentence is long because it enumerates dimensions, but each clause carries 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 7-parameter, zero-required tool with a nested object, the description explains persistence scope and the downstream consumer (export_data_slice) well. The remaining gap is that 'show' presumably returns the current POV and no output schema exists, so an agent does not know the shape of that response.

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 every parameter (pov, year, entity, planType, scenario, connection, action) is already documented, including the empty-string removal trick and the connection default. The description only adds the semantic frame that these members are reused by export_data_slice when a request omits them; it adds no format or syntax 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?

The description names concrete verbs (shows, sets, clears) and a specific resource (the connection-scoped point of view: scenario, year, entity, cube, other dimension members). It also distinguishes the tool from the sibling that consumes its state (export_data_slice), so an agent can tell what it does and what it feeds.

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 concrete triggers: the user asks to keep looking at the same entity/year, to switch context for upcoming questions, or to start over. That covers show/set/clear selection implicitly. It stops short of an explicit 'do not use this when…' clause or naming a true alternative tool, so it is clear context rather than a full when/when-not/alternatives contract.

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/openWorld/idempotent/non-destructive, yet the description adds substantial context beyond them: entries are per user, retained only for the days set by the policy's answers.historyDays, and can be forgotten via the portal Usage page. It also discloses that some entries store numbers while others store only a per-cell hash, which explains why a comparison may be limited.

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 dual-mode behavior is front-loaded in the first sentence, followed by retention and usage. It is dense and the first sentence is long, but every clause carries information; only the slight run-on quality keeps it from a 5.

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 output schema, the description carries the burden of explaining returns and does so: it enumerates the listed fields and states that the comparison reports whether numbers changed and which cells. Retention policy and per-user scoping round out what an agent needs to call it and interpret results 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 baseline is 3, but the description adds genuine meaning the schema does not: the two parameters are really two modes — limit lists newest-first, and supplying a fingerprint switches to re-read-and-compare. That mode-switching semantics is the key thing an agent needs and is not 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+resource (lists remembered data slices) and explicitly describes the second mode: given a fingerprint, it re-reads that slice from Oracle and reports whether numbers changed. The enumerated per-entry fields (connection, application, cube, point of view, read time, cell count, stored vs hash) make the resource concrete and distinguishable from 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?

Gives explicit triggers: when the user asks what a slice showed before, whether numbers moved since an earlier answer, or to compare today's read with a remembered one. No sibling is named as an alternative or exclusion, which keeps it short of a 5, but the usage context is clear enough that an agent will pick it over export_data_slice or get_job_status.

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 and non-idempotent, so this description only needs added context — and it delivers: it discloses that the rule mutates data in Oracle, that the call returns before completion (async), and that the confirmation token lasts ten minutes and is single-use. That is exactly the extra behavioral context annotations cannot express.

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

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

Four sentences, front-loaded with the action, followed by side effects, usage trigger, and the confirmation protocol. No filler; the token-lifetime sentence is repeated from the schema but serves the safety-critical confirmation flow.

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?

No output schema exists, and the description compensates by naming the return value (job id) and the async follow-up path via check_job_status. For a destructive, non-idempotent, open-world mutation with a nested parameters object, the agent has everything needed to call it 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?

Schema coverage is 100%, and the description largely restates what the schema already documents (confirm, confirmationToken lifetime, job-id return). It adds the preview-then-confirm sequencing relationship between confirm and confirmationToken, which is modest added value over per-field descriptions; 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+resource ('Launches a business rule (calculation script)') plus the return value ('returns the job id'), which immediately separates it from read-only siblings like list_applications or get_effective_policy. The parenthetical and the 'runs in Oracle' note make the resource unambiguous.

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 trigger ('when the user wants a calculation, aggregation or allocation run') and routes the agent to the correct follow-up sibling, check_job_status. Leaves one gap: it says a preview is required before a write but, since no preview sibling exists, the agent must infer that omitting confirm on this same tool produces the preview.

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 disclosing blast radius (change applies to every form, rule and report), a mandatory preview-then-confirm flow, a 10-minute token lifetime and single use. That is exactly the extra context destructiveHint/openWorldHint 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-loads the action and example, then scope, then the safer alternative, then the gating workflow. Every sentence carries information, though the first-person 'I require' phrasing is slightly informal and the token details partly duplicate the schema description.

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, open-world, 7-parameter write with no output schema, the description covers impact, safeguards and timing. It stops short of naming the specific tool that produces the preview/confirmationToken, which is the one operational detail an agent still needs to infer.

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 earns above that by explaining the sequencing semantics of confirm and confirmationToken ('preview first, then confirm: true and its confirmationToken') rather than just restating field definitions.

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 ('Sets a substitution variable to a new value') plus a concrete example (CurrMonth Mar→Apr) and the blast radius ('every form, rule and report'). It is cleanly distinguishable from the read-only sibling get_substitution_variables.

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 trigger ('when the user asks to move a period, year or scenario pointer') and points at a safer alternative (change set with plan_change and run_change). Minor weakness: plan_change and run_change are not in the sibling tool list provided, so the routing hint points at names the agent may not be able to resolve.

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

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

The description says the tool 'Creates the demo EPM connection' and 'makes it the default when the user has no default connection', which are state-changing actions. The annotations declare readOnlyHint=true, so the description contradicts the safety profile; this is an annotation contradiction.

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 includes only operationally relevant details: sample data, reuse behavior, default behavior, return value, plan availability, and usage condition. It is dense but appropriately sized.

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

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

The description covers what the tool does, what it returns ('ready-made prompts'), plan availability, and when to use it. With no output schema, the return value is briefly but adequately described; the main remaining gap is the annotation inconsistency, scored separately.

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 no parameter semantics to explain. The baseline for a zero-parameter tool applies, and the description needs no parameter details.

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

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

The description uses a specific verb and resource: 'Creates the demo EPM connection with sample data'. It distinguishes the demo environment from a real Oracle EPM pod and clearly names the Vision application, so an agent can tell it apart from connect_epm_environment.

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 a clear usage condition: 'Use it when the user has no connection yet and wants to try the connector before adding a real Oracle EPM pod.' That is a strong contextual cue, though it does not explicitly name connect_epm_environment as the alternative for real connections.

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