Arsen MCP

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them with interpretive semantics the schema cannot carry: PROCESSING means reporting is still being finalized, no status-transition timestamp exists, the scheduled date is not a delay diagnostic, and null rates mean unavailable rather than zero. That directly prevents the most likely agent misreadings.

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 sentence, and the remaining three sentences are dense caveats with no filler. The trailing caveat cluster is slightly compressed and could be split for readability, 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?

An output schema exists, so return values need no prose, and annotations handle safety; the description covers the non-obvious result semantics thoroughly. What is missing is only the meaning of the two required identifiers, which leaves a small gap for a two-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?

Schema description coverage is 0% and both parameters are required, so the description carries the full burden. It never mentions organization_id at all and only obliquely implies campaign_id via 'one simulation campaign'; the agent must infer that organization_id is the owning-org scoping key.

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?

Specific verb and resource with scope: 'Read privacy-safe outcomes, rates, timings, score, and schedule for one simulation campaign.' The phrase 'one simulation campaign' distinguishes it from the sibling search_campaigns, and the enumerated payload fields tell the agent exactly what comes back.

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: 'one simulation campaign' suggests a per-campaign detail lookup versus search_campaigns, but the description never states when to call this instead of get_organization_overview or search_campaigns, nor any prerequisite for obtaining campaign_id. There are no exclusions or alternative 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses substantial behavioral context: per-section scope and freshness, partial results and stale metadata, read_at not being an atomic snapshot, null-vs-zero semantics, rate/score scales, simulation period defaults, and endpoint observations being six months of phishing data rather than a live inventory. These details materially improve safe interpretation of 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?

The purpose is front-loaded, but the body is a dense single block of long sentences that is difficult to scan. Most content is relevant, yet there is some redundancy, such as repeating that unrequested sections are omitted, and the compressed lists would benefit from clearer structure.

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 multi-section read tool with an output schema, the description is remarkably complete on section behavior, defaults, permissions, formatting conventions, freshness caveats, and partial-result handling. Some lower-level parameter mechanics remain unexplained, but the essential context an agent needs to call and interpret the tool is present.

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 0%, so the description must carry the semantic burden, and it largely does: it explains what scoring, groups, insights, recommendations, endpoints, simulation, and training sections mean, including defaults and permissions. It still leaves some nested mechanics such as query/cursor/limit behavior and the statuses enum unexpanded beyond their structural names.

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 first sentence states a specific verb and resource: read the Reporting dashboard and Training program for an Organization. It is clear what the tool returns at a high level, but it does not explicitly distinguish itself from sibling tools such as get_campaign_summary or search_campaigns.

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 some usage context: at least one section must be requested, only requested sections are read, groups and recommendations require Admin/Owner, and Training does not accept the Simulation period. However, it never states when to choose this overview tool instead of a sibling tool, nor does it provide explicit exclusions or alternatives.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one piece of genuine context beyond that — the result set is scoped to organizations 'accessible to the authenticated User' — which tells the agent results are permission-filtered. It says nothing about result volume, ordering, 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?

A single sentence with no filler, front-loading the action and the resource. Nothing is wasted and nothing essential is delayed.

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 tool with full annotation coverage and an output schema, the description is essentially sufficient — return structure need not be explained. The only small gap is the absence of any hint about result ordering or whether the list can be large, which would matter for an agent planning follow-up calls.

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 and the baseline of 4 applies. Schema coverage is 100% and the empty property set is consistent with a simple enumeration call.

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 (List) and resource (organizations), making the operation immediately identifiable. It does not differentiate itself from siblings like get_organization_overview, but the resource name plus the enumeration verb is clear enough that an agent can distinguish a list operation from an overview or search operation.

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

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

Usage is only implied: an agent can infer this is the entry-point discovery call to find organizations before calling organization-scoped tools such as get_organization_overview. There is no explicit statement of when to use this versus the sibling tools, nor any prerequisite or exclusion noted.

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 behavior, so safety needs no restating. The description adds genuinely non-obvious context: result ordering is by created_at rather than scheduled_at, page continuation goes through next_cursor, and PROCESSING is a finalization state rather than a failure or backlog signal.

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, each with a distinct job: scope, result ordering plus pagination, status interpretation. The most load-bearing constraint (ordering by created_at, not scheduled_at) is stated early 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?

An output schema exists, so return values need not be described, and the pagination, ordering, and status semantics an agent most often gets wrong are covered. Gaps remain for a 9-parameter tool: no mention of the limit default/cap, the required organization_id, or what the goal and use_case enum values mean.

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 0%, so the description must carry parameter meaning, and it does map five facets to parameters plus explains the PROCESSING status value. However, organization_id, limit, cursor (only alluded to via next_cursor), and the enum meanings of goals and use_cases receive no explanation.

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?

"Find simulation campaigns" pairs a specific verb with a specific resource, and the facets listed (name, lifecycle state, goal, use case, schedule) match the schema's filter parameters. It does not explicitly distinguish itself from the sibling get_campaign_summary, so it stops short of the top mark.

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 search facets imply this is the discovery tool to use before fetching a summary, but the description never says when to use it instead of get_campaign_summary or list_organizations. No prerequisites, exclusions, or alternative routing 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 read-only, idempotent, non-destructive, closed-world behavior, yet the description adds substantive traits beyond them: results are not an atomic cross-store snapshot, retained history stays readable when a program is disabled, deleted Training sessions are excluded, and evidence is never silently truncated. The pagination contract is unusually well disclosed (continue with next_cursor even after an empty activity page; null means exhausted; read_at is retained across pages), which is exactly the kind of behavior an agent cannot infer from 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?

Purpose is front-loaded and the remaining sentences are dense rather than padded, but it is a single long paragraph covering purpose, selection, pagination, consistency, and error recovery with no structural breaks, making it harder to scan. A few clauses restate schema content (cursor continuation, limit reduction) that could have been dropped without loss.

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 nested, two-branch, cursor-paginated search over a deeply nested activity schema, the description covers the selection model, per-source return contents, ordering, pagination termination, snapshot consistency, and retention semantics. Because an output schema exists, it correctly stops short of enumerating return fields, giving an agent everything needed to call it correctly across pages.

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 still adds value by clarifying that limit caps both the number of matching Employees selected and the number of activity records returned, and by stating result ordering (Employee ID then channel and Campaign ID for Simulation, or session ID for Training). It also enumerates the Employee selection modes (IDs, literal name/email, Groups/Dynamic Groups, active state) and warns that activity filters do not select Employees. It does not explain the TRAINING period.field choices, which the schema already covers well.

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

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

The description opens with a specific verb and resource: 'Inspect the retained evidence behind Employee Simulation and Training posture within one Organization.' It then names the two concretely distinct modes (SIMULATION returns campaign/channel participations with outcomes and source events; TRAINING returns assignments with lifecycle dates and MCQ answers), so an agent can distinguish this from searchEmployees and search_campaigns 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 explicitly routes the agent: 'Use searchEmployees for summaries or comparisons,' and 'omit selection to browse' when no filter is needed. It also constrains the call shape ('Choose exactly one activity.source per call') and gives a recovery path ('If a page is too large, reduce limit or narrow selection and filters'), which covers both when to use this and when a sibling is the better choice.

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 read-only/idempotent/non-destructive, yet the description adds materially new behavior: Admin/Owner permission needed for scoring, history mode capped at five exact IDs and limit five with 30 UTC sampled points, current-only scoring supporting the ordinary 50-employee page, and the crucial caveat that insight filters narrow evidence rather than Employee selection. It also clarifies the return shape (one summary per Employee with pagination, not individual observations or Learner Sessions), which goes well beyond the annotations.

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

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

Content is front-loaded: purpose and selection mechanics come before the summary-shape details. It is a single dense paragraph of many sentences, though, and a short bulleted split between selection rules, output contents, and constraints would improve scanability without losing 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 deeply nested, five-parameter tool with high complexity, the description covers selection semantics, per-section behavior, permission requirements, pagination/history limits, and what the response contains. Since an output schema exists, it correctly stops short of exhaustively documenting return fields while still flagging the summary-level granularity.

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

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

Schema description coverage is 100%, so the baseline would be 3; the description earns an extra point by adding semantics not present in the schema, notably that an empty object requests a section without evidence filters, that insight filters affect summarized evidence rather than selection, and the history-mode ID/limit/point caps. It still leaves some nested details (e.g. how `match` interacts with `ids` plus `query`) to 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 opening sentence names a specific verb (Find/return) plus resource (Employees within one Organization) plus the exact payload (Simulation, Training, canonical scoring summaries). The description also explicitly carves out scope against alternatives with "Does not discover, filter, or rank Employees by score," so an agent can distinguish it from sibling tools like search_employee_activity 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 concrete when-to-use cases (inspect one Employee, compare selected Employees, review a Group or Dynamic Group) and a how-to-select rule (by IDs or literal name/email, omit filters to browse). The main gap is that it never names a concrete sibling tool as the alternative, stating only the negative constraint that it does not rank or discover by score.

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