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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds only that portals target external users and can be configured in various ways; it omits side effects such as whether recipients are notified on creation or what identity/permissions are required.

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 core action, followed by a capability overview and the required-fields note. Efficient, with no filler, though the middle feature list is somewhat marketing-flavored rather than task-critical.

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 33-parameter creation tool with nested objects and no output schema, the description covers the essentials (what it creates, required vs optional fields) but says nothing about the returned identifier an agent would need for follow-up calls. Adequate but with real gaps.

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 33 parameters, including nested objects and conditional dependencies. The description's feature list (access codes, download passwords, file type restrictions, branding, integrations) loosely maps to parameters but adds no syntax or format detail beyond the schema, 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 ('Create a new portal') plus the scope ('for collecting files from external users'). It is easily distinguished from the read/update/delete portal siblings, 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?

No guidance on when to create a portal versus using update_portal on an existing one, no prerequisites, and no mention of permissions or limits. The only conditional info is about optional parameters, which is parameter rather than usage 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 flag destructiveHint=true and idempotentHint=true, so the description goes further by disclosing the exact blast radius ('all its files'), irreversibility ('cannot be undone'), and an environment-variable prerequisite that appears nowhere in 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?

Three short sentences with zero filler, leading with the action and immediately following with the destructive consequence and prerequisite. Every sentence 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 single-parameter destructive tool with no output schema, the description covers scope, consequence, irreversibility, and the auth prerequisite. Nothing an agent needs before invoking it 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% and the single packageId parameter is already documented in the schema. The description's 'by ID' adds no format, validation, or sourcing detail beyond that, so it earns the baseline 3.

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 ('Delete a package by ID') with no ambiguity. It is clearly distinguishable from read siblings like get_package and from the only other delete tool, delete_portal.

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 required MASV_ALLOW_DELETE=true prerequisite is genuinely useful usage context. However, it never states when to choose this over alternatives or any caveats about which package IDs are valid, leaving usage 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?

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing that deletion is permanent and irreversible, that packages uploaded to the portal remain accessible afterwards, and that an environment flag gates the operation. These are exactly the consequences an agent needs before calling 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 short sentences, front-loaded with the action and ID, then irreversibility, side effects, and the gating variable. Every sentence carries distinct information with no repetition.

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 one-parameter tool with no output schema, the description covers action, irreversibility, downstream side effects on packages, and the auth/environment requirement. 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 description coverage is 100% with a single required 'portalId' whose schema text already explains it. The description's 'by ID' adds nothing beyond the schema, so the baseline 3 for fully-documented parameters 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 ('Delete a portal') plus the keying parameter ('by ID'). The resource is clearly distinct from the sibling delete_package, so an agent can disambiguate 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?

Provides a concrete precondition for use — the MASV_ALLOW_DELETE=true environment variable must be set — which tells the agent when invocation will succeed. It does not name alternatives or explicit when-not conditions, but the prerequisite is meaningful operational 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?

The readOnlyHint annotation already tells the agent this is a safe read, lowering the bar. The description adds useful domain context (activity states and the enumerated activity types, plus the fact that activities carry associated events), but says nothing about pagination behavior or the shape of returned records. Adequate but not rich beyond the annotation.

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 opening 'Get activities' is front-loaded and efficient, but the remainder is a long enumeration of activity types whose parenthetical explanations restate the schema's enum descriptions verbatim, adding bulk without new information. Moderately verbose for the value delivered.

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 ten filter parameters, no output schema, and only a readOnlyHint annotation, the definition should ideally describe what a returned activity contains and how pagination/sorting interacts with the filters. It covers domain terminology well but leaves the return structure and paging semantics to inference, so it is only minimally 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 description coverage is 100%, so all ten parameters including filters and the activity_types/activity_states enums are already documented. The description's enumeration of types and states largely duplicates what the schema enums already carry, so it adds little semantic meaning beyond the structured fields. 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 states a clear verb+resource ('Get activities') and goes further to define what an activity actually is (records of events on packages, links, transfers), so an agent knows the domain object being retrieved. However, it never distinguishes this tool from siblings like get_activity_events or get_activities_information, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance and no alternatives named. It mentions that 'each activity has associated events,' which hints at a relationship to get_activity_events, but it never says 'use X for events' or when to prefer this listing tool over get_activities_information. No exclusions or prerequisites either.

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 and openWorldHint=false, so safety is covered. The description adds no behavioral value beyond that: nothing about return format, pagination, state enumeration, or what 'accurate states' actually entails. It essentially restates its own purpose in the second sentence.

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, but the second is largely redundant with the first and is grammatically awkward ('use this tool provide users with'). The first sentence also stacks 'detailed information' and 'accurate states description' without adding precision. Some trimming is warranted.

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 no-param, read-only, annotation-covered tool the description is minimally adequate, but it omits what an 'activity' or a 'state' is and how this differs from get_activities/get_activity_events. Given the crowded sibling set, more context is needed to invoke 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 takes zero parameters, so the baseline is 4. There is no parameter syntax for the description to clarify, and it correctly implies the tool takes none.

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 ('Get detailed information about all existing activities') and adds that it covers their states. However, it does not distinguish itself from the sibling tools get_activities and get_activity_events, so an agent cannot tell from the description alone why it should pick this tool over those.

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 second sentence ('Always use this tool provide users with detailed explanation about activities and their states') is a directive but gives no when-to-use conditions or alternatives. With closely related siblings (get_activities, get_activity_events) available, the absence of routing guidance is a real gap.

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 readOnlyHint annotation already establishes that this is a safe read, so the bar is lower. The description usefully adds the data-model insight that events accumulate on every state transition. It says nothing about ordering, pagination, or result size, so it is adequate but not rich.

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

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

The core action is front-loaded in the first sentence, and the rationale follows efficiently. The middle sentence ('Activity gets event record every time it transitions to a new state') reads slightly awkwardly and repeats the transition idea, but the length is reasonable for the information conveyed.

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 single-parameter read tool with no output schema and full schema coverage, the description supplies enough to call it correctly and understand why it exists. Missing return-shape and ordering details are minor since no output schema is provided and could reasonably be discovered at call time.

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 whose meaning ('Id of the activity to retrieve events for') is fully documented in the schema at 100% coverage. The description adds no syntax, format, or sourcing detail beyond that, 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 states a specific verb and resource: retrieve the event history for a given activity. It also explains what an event is (a record created on each state transition), which gives the agent a concrete mental model. It does not, however, explicitly distinguish this from siblings like get_activities_information, which could be confused with 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?

It gives a clear reason to use this tool: since an activity only stores its current state, the event history is needed to learn how it got there. That is usable context for selection. It stops short of naming an alternative or stating explicit exclusions, so it is not a full when/when-not treatment.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description is consistent with that. It adds useful domain context about what an integration is, but says nothing about result ordering, pagination, or account scoping, so the behavioral disclosure is only partial.

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, the purpose front-loaded and the examples following. No filler, no repetition 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 simple parameterless listing tool with no output schema, the description covers the essential purpose. It would be stronger if it hinted at what the returned integrations are used for (e.g. feeding ids into the file/transfer tools), but nothing critical 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 schema cannot be augmented and there is nothing for the description to clarify. Baseline for a no-parameter tool 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 clear verb+resource ('Get list of connected integrations') and illustrates the domain with concrete examples (AWS S3, Frame.io, Dropbox, MASV Storage Gateway). It implicitly separates itself from file-level siblings, but never names them, so differentiation is left to inference.

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?

There is no explicit when-to-use guidance and no mention of alternatives such as list_files_on_integration or send_package_to_integration, which share the 'integration' concept. An agent must infer that this is the discovery step before those tools.

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, so the safe-read profile is covered. The description adds nothing beyond that — no note on error behavior for a missing id, no indication of what a 'package' contains, and no operational 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?

A single five-word phrase with zero waste and the key retrieval constraint front-loaded. It is efficient, though arguably under-specified rather than deliberately terse.

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 one-parameter lookup with no output schema, the schema and readOnly annotation carry most of the burden, so minimal prose is tolerable. Still, nothing describes what a package represents or how the agent should react to a not-found id.

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 parameter is fully documented, so the schema does the work. 'By id' merely restates what the schema already says, adding no format or constraint 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?

States a specific verb and resource ('Get package by id'), and the singular form implies a single-resource fetch vs the plural 'get_packages' sibling. However, it never explicitly distinguishes itself from get_packages or get_package_files, leaving the agent to infer the boundary.

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?

There is no when-to-use guidance, no mention of when to prefer get_packages instead, and no prerequisites. Usage is only implied by the name itself.

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, so the safe-read profile is covered by structured data. The description adds essentially nothing beyond that: no pagination behavior, ordering, whether missing files or an invalid packageId yields an empty list or an error, and no indication of result size limits.

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 short, front-loaded sentence with no filler or repetition. It is efficient, though its brevity borders on under-specification rather than deliberate conciseness.

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?

This is a simple one-parameter read tool with annotations covering safety and no nested objects, so heavy documentation is not required. However, with no output schema, the description gives no hint of what the returned file list contains or its shape, leaving a real gap for an agent deciding whether this tool answers its question.

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 parameter packageId is fully documented in the schema as 'Id of the package to retrieve files for'. The description adds no format, source, or constraint 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 (get/list) and resource (package files), which is enough to distinguish it from sibling tools like get_package and get_packages that operate on package metadata rather than their contents. It does not explicitly name those siblings or clarify the boundary, keeping it 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?

There is no when-to-use guidance, no prerequisites (e.g., that the package must exist or be accessible), and no mention of alternatives such as get_package or list_files_on_integration. The agent must infer all routing from the name alone.

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 so safety is covered. The description adds a useful scoping insight (team-only, excludes Portals), but says nothing about pagination behavior, default limits, or result ordering despite the schema exposing page/limit/sort.

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 core action, and no filler. Slightly redundant in restating 'MASV' twice but efficient 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?

Given 13 optional filters fully documented in schema and readOnly annotations, the description covers the key semantic distinction (team vs portal). It could still note pagination or that the full inventory needs two calls, but it is largely sufficient 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 fully documents all 13 filters including status semantics and date formats. The description adds no parameter syntax or intent, 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?

Specific verb 'Get' and resource 'team packages', and it explicitly distinguishes team packages from portal packages ('does not include packages sent to Portals'). However, it doesn't name the sibling tool get_portal_packages that returns the other half, leaving the agent to infer the pairing.

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?

States that this returns only team packages and that a full list requires combining with portal packages, which implies when to use it. But it gives no explicit condition telling the agent to call get_portal_packages or when this alone is sufficient.

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?

readOnlyHint=true already tells the agent this is a safe read, so the burden is lighter. The description adds useful domain context about what a transfer is (MASV delivery to cloud/on-premise via Storage Gateway) but says nothing about pagination, ordering, or result shape.

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 the action and scope. The second sentence is a definition, which is helpful but largely duplicates the packageId schema description, costing a little efficiency.

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 single-parameter read-only list tool with no output schema, the description covers the action, scope, and the domain concept of a transfer. Nothing essential to invoking 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% and the single parameter's schema description is nearly identical to the tool description, so the description adds no meaning beyond the structured field. Baseline 3 applies when the schema does all the work.

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 ('Get all transfers of a package') and defines the domain term 'transfer' as a delivery via MASV to cloud or on-premise destinations. This distinguishes it from siblings like get_package_files, though it never names an 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives among the many package-related siblings. The phrase 'to storage' implies the scope but leaves selection between get_package_files, get_package, and this tool 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=true, so safety is covered by structured data. The description adds value by disclosing what the response contains (configuration, recipients, connected integrations, settings), which helps the agent decide whether this call will supply the data it 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?

Two sentences, front-loaded with the action and followed by the return contents. No filler, though the second sentence is a straightforward enumeration rather than something the agent could not infer from the name.

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 single-parameter read tool with no output schema, the description is nearly sufficient: it tells the agent what to pass and what comes back. Nothing critical is missing, though it could note behavior for an invalid or nonexistent portal ID.

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?

Single parameter with 100% schema description coverage, so the schema fully documents portalId. The description's 'by ID' merely restates that, adding no format or constraint detail. 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 ('Get a specific portal by ID') and enumerates the returned content. The word 'specific' implicitly distinguishes it from the sibling get_portals, but no sibling is named explicitly, so it falls short of full differentiation.

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

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

Usage is only implied: retrieve a single portal when you have its ID, versus the sibling list tool get_portals. There is no explicit when-to-use guidance, prerequisites, or named alternative.

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 readOnlyHint annotation already declares this a safe read. The description adds genuine scoping behavior - it returns ONLY portal-hosted uploads and omits team packages - which is useful. It says nothing about pagination or result shape for a 14-parameter list tool, so it does not go far beyond the annotation.

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, scope stated up front, no filler. The middle sentence is grammatically broken ('Only packages that were uploaded to Portals returned by this tool' is missing a verb), which slightly hurts readability but not length.

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-required, 14-parameter listing tool with no output schema, the description covers the essential scope distinction but omits return format, pagination behavior, and default sort/limit semantics. The rich schema compensates for filters, but the description is thin relative to the tool's complexity.

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 14 parameters (filters, pagination, sort, date ranges) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, 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 ('Get portal packages') and defines the resource precisely: packages uploaded by anyone to MASV Portals. It distinguishes this from the broader package set by noting you must combine team packages and portal packages, though it never names the sibling get_packages 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 implied ('To get full list of packages you need to get both team packages and portal packages'), which tells the agent this is one half of a complete listing, but the alternative tool is not named and there is no explicit when-not-to-use guidance.

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

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

With readOnlyHint=true already declaring the safe-read profile, the bar is lower. The description adds domain context (portals collect files from external users, each has a subdomain and configurable settings), which is useful background, but it discloses nothing operational about pagination, default page size, or list 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?

The first sentence is well front-loaded, but the third sentence enumerating portal capabilities (upload/download password, file type restrictions, integrations, metadata forms) is padding that does not help an agent filter or sort the list. It is borderline verbose for a simple list operation.

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 list tool with no output schema and full schema coverage, the essential invocation information is present. Still, it omits what the list returns and pagination defaults, so it is adequate but not 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 all seven filter/sort/pagination parameters are already documented in the schema. The description adds no parameter syntax or format detail beyond that, 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?

The description clearly states a specific verb and resource ("Get list of portals") and scopes it to the team. However, it does not distinguish itself from the singular sibling get_portal, leaving the agent to infer the list-vs-single 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?

No guidance on when to use this tool versus alternatives such as get_portal, or when portal listing is appropriate. The definition describes what portals are but never addresses selection conditions or exclusions.

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 readOnlyHint=true, so the description carries the burden of output disclosure, which it does by listing the exact member fields returned. It does not mention pagination or result-size limits, but 'all team members' implies a complete, unpaginated list, making this reasonably transparent for a safe read 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?

Two sentences, both front-loaded and purposeful: the first states the action, the second lists return fields and the reason to call it. Nothing is redundant with the title or schema, and there is 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 no output schema and an empty input schema, the description must supply the return contract, and it does so by enumerating the member fields and the cross-tool use case. The only gap is the absence of any note on ordering, pagination, or permissions, which is minor for a parameterless read 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. The empty schema means there is nothing for the description to clarify or compensate for, and the description correctly implies no filtering inputs are required.

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 ('Get list of all team members') and enumerates the returned fields (id/membership_id, email, name, policy, approval status, teamspaces), which no sibling tool provides. It also states its unique downstream role (supplying membership IDs), so an agent can immediately distinguish it from the portal/package 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?

It gives an explicit when-to-use: obtaining membership IDs needed for 'portal access_list when creating private portals.' There is no competing sibling that lists team members, so no when-not guidance is required, but the description stops short of stating exclusions or prerequisites (e.g., permissions needed).

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, so the safety profile is covered. The description adds genuine behavioral context by disclosing pagination and the cursor round-trip, but the cursor mechanics largely restate the schema's own cursor description and it says nothing about ordering, limits, or error 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?

Two compact sentences, with the listing purpose front-loaded and pagination second. No filler, though the pagination sentence is slightly redundant with the cursor parameter 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 read-only, three-parameter listing tool with full schema coverage and no output schema, the description covers purpose and the one non-obvious interaction pattern (cursor paging). Only minor gaps remain, such as result ordering or whether listing is recursive.

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 (path, cursor, integrationId) are already documented in the schema. The description adds no semantics beyond that, which is the expected baseline when the schema does the work.

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 ('List files on any integration') and names the supported integration types (cloud or MASV Storage Gateway). It does not explicitly distinguish itself from siblings like get_package_files or transfer_files_from_integration, 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?

The description implies usage contexts by naming the two integration kinds, and the pagination note implies repeated invocation, but it never says when to prefer this over siblings or any preconditions such as needing a valid integrationId.

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 destructiveHint=false and readOnlyHint=false, so the safety profile is already covered. The description adds nothing behavioral beyond that: it does not say whether the package is copied or moved, whether the operation is async, what permissions are needed, or whether it consumes quota. The integration examples describe the destination, not the 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?

Two short, front-loaded sentences with no filler. The second sentence's enumeration of integration types is mildly useful context, though it slightly pads the entry without changing how the tool is invoked.

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 no output schema and sparse annotations, the description is minimally viable: it conveys what the tool does but omits the masv_to_cloud prerequisite, what the caller receives back, and what happens to the package after delivery.

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 both parameters, and the schema already documents packageId and integrationId including the direction: masv_to_cloud constraint. The description adds no syntax, format, or default 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?

The description states a clear verb+resource ('Send MASV package to connected integration') and names the concrete destination types (AWS S3, Frame.io, Dropbox, MASV Storage Gateway). It does not explicitly contrast with the directional sibling transfer_files_from_integration, so an agent must infer the direction from the wording rather than being told.

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?

There is no when-to-use guidance, no prerequisites stated, and no exclusion of alternatives. The reader is not told when this is preferred over transfer_files_from_integration or list_files_on_integration, nor that the target integration must have direction masv_to_cloud (that constraint lives only in the schema).

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=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds the meaningful behavioral fact that it both creates a package and initiates the transfer, but says nothing about whether the transfer is synchronous, how failures are surfaced, or any permission/rate constraints.

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 with no filler, front-loaded with the action and the supported sources before the prerequisite. Placing the list_files_on_integration prerequisite at the end is slightly less ideal than front-loading it, 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 mutation tool with no output schema, the description covers purpose, scope and prerequisite but omits what the call returns (e.g. package ID/handle) and gives no context on optional parameters like recipients, accessLimit, or notifyEmail, which the schema documents but the description leaves untouched.

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 is already documented in the schema, including the file ID semantics and kind enum. The description only indirectly reinforces where the file IDs come from via list_files_on_integration; 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?

Specific verb+resource with direction of flow stated ('Transfer files from a cloud integration... to MASV') and an enumeration of supported sources (AWS S3, Azure, Dropbox, MASV Storage Gateway). It also notes the side effect (creates a new package). It does not explicitly contrast itself with the reverse-direction sibling send_package_to_integration, so differentiation is only implicit.

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 concrete prerequisite: 'Use list_files_on_integration first to get file information including IDs,' which tells the agent this tool cannot be called cold. No exclusions or alternative routing (e.g. when to use send_package_to_integration instead) are provided.

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, so the safety profile is partly covered. The description goes further by disclosing the irreversible consequence ('the package and all of its files are deleted and can not be restored') and the cost implication of added storage, which annotations cannot convey. It does not discuss auth/permission requirements.

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, purpose front-loaded, with the destructive warning kept brief. Slightly loose as a block of statements rather than a structured list, 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 destructive, idempotent mutation tool with full schema coverage and no output schema, the description supplies the key consequence and cost context an agent needs. Missing only permission/authorization notes and any guidance on restoring or reversing behavior short of the hard warning.

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

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

Schema description coverage is 100%, including the interdependency between expiry and unlimited_storage, so the schema carries the parameter semantics. The description adds no format, boundary, or interaction detail beyond what the properties already state; 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 a specific verb and resource (update package expiration date and time) and adds a second capability (enabling/disabling unlimited storage). An agent can tell this apart from delete_package or get_package. It stops short of explicitly contrasting itself with any sibling, so it sits at a clear-but-not-routing 4.

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 tool is for changing expiry or toggling unlimited storage, and the destructive consequence hints that it is the path to eventual deletion. There is no explicit when-to-use, when-not-to-use, or alternative (e.g. delete_package for immediate removal) named.

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=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds nothing beyond that: it never mentions that this is an irreversible mutating operation, never explains partial-update semantics (whether omitted fields are preserved or reset), and never warns about the required-field coupling (e.g. expiry required when expiry_enabled=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?

Two short sentences, front-loaded with the action and scoped by the second. No filler or repetition, though the trailing 'and more' is vague rather than informative.

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 34-parameter destructive mutation with nested objects and no output schema, the description is far too thin. It omits partial-update behavior, the required-field interlock for expiry/access_code/download_password/terms_of_service, and which changes are destructive or hard to reverse.

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 34 parameters are already documented in the schema, and the baseline is 3. The description adds only a high-level categorization of the setting groups and no parameter-level meaning beyond what the schema already states.

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 ('Update') and resource ('an existing portal's configuration') and enumerates the categories of settings it touches. It does not distinguish itself from siblings such as create_portal or delete_portal, but the CRUD intent is 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?

'Use this to modify portal settings like access controls, branding, file restrictions, and more' implies the when but names no prerequisites, no when-not, and no alternative tool. An agent must infer that this only applies to already-existing portals.

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