Aident AI

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

Annotations only indicate readOnlyHint: false, which is minimal. The description compensates by disclosing key behavioral traits: actions are not read-only (they can activate, request payouts, and permanently attach codes), and there's a specific 60-day post-signup constraint. It also implies side effects like irreversible code attachment, which is valuable transparency.

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 a single sentence that efficiently enumerates the tool's core actions and a critical constraint (60-day window). Every phrase earns its place, and it's appropriately sized for the tool's complexity.

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 no output schema, minimal annotations, and a 3-param tool, the description provides sufficient context by naming all actions and the time limit. It could elaborate on side effects (e.g., idempotency of activate) but is complete enough for typical use cases.

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 67% (two of three params described), so the baseline is 3. The description's 'permanently attach an affiliate code' adds meaning to the 'code' parameter beyond schema, and 'request a payout' clarifies 'request-payout' action. However, it doesn't fully explain interactions between parameters (e.g., termsAccepted requirement).

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 the tool's purposes: activating/inspecting an affiliate account, requesting a payout, or attaching an affiliate code. While it names several actions, they map directly to the action enum values, making the purpose clear. It doesn't explicitly distinguish from sibling tools, but the affiliate-specific scope is evident.

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 when to use the tool ('Activate or inspect your Loadout affiliate account...') but doesn't explicitly contrast with alternatives or state when NOT to use it. The 60-day constraint and permanent code attachment provide important usage context, but there are no exclusions or references to sibling 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, and the description's 'Inspect or summarize' aligns with that. The description adds useful scope context ('current account') and indicates the tool returns recent data. No contradictory behavior is mentioned. While it doesn't disclose rate limits or detailed side effects, the read-only nature is clear from both the annotation and description.

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 a single, concise sentence with a clear verb-first structure. It avoids unnecessary detail and is easy to parse. Every word 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?

For a read-only audit tool with 8 parameters and no output schema, the description provides enough context: it explains what the tool does, the scope (current account), and the two modes (inspect/summarize). The schema covers parameter details. It does not explain return format, but since no output schema exists, a brief mention would be helpful, though not essential for correctness.

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 88% (7 of 8 parameters have descriptions), so the baseline is 3. The tool description adds minimal parameter semantics—it mentions 'recent' and 'summarize' which map to the 'action' parameter, but that is already covered by the schema's enum description. No significant additional meaning is provided.

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 the tool's function: 'Inspect or summarize recent Loadout action calls for the current account.' It uses specific verbs ('inspect', 'summarize') and a resource ('Loadout action calls'), and distinguishes from siblings by focusing on audit/usage, which none of the sibling tools (auth, billing, capabilities_*) cover.

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 provides clear context for when to use the tool (to view recent or summarized Loadout action calls for the account). It does not explicitly exclude alternatives or mention when not to use it, but the context is sufficient given the unrelated sibling tools. This is slightly below explicit guidance (which would be 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?

The annotations include readOnlyHint: false, indicating the tool may have side effects. The description lists 'log out' and 'get login instructions' which aligns with mutation, but it is ambiguous whether 'login' performs the actual login or merely provides instructions. This ambiguity is not fully disclosed, and the description adds minimal extra context beyond the annotation. The mention of the SETUP.md update is unrelated and does not clarify 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 concise and informative, but the second sentence about refreshing SETUP.md is a tangent that does not directly relate to using this tool. It adds noise rather than value, reducing the overall conciseness. The structure is otherwise clean, but the extra instruction could confuse the agent.

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 tool is simple (one parameter, no output schema), so the description covers the main actions and their purposes. However, it fails to clarify the exact behavior of the 'login' action (whether it authenticates or just provides instructions) and does not mention what the tool returns or any prerequisites. The second sentence about SETUP.md is irrelevant to the tool's operation. Given the tool's simplicity, the description is adequate but not fully complete.

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

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

The schema has a single parameter 'action' with enum values and a default, but no property descriptions. The description compensates by explicitly mapping the enum values to human-readable actions: status, login (as 'get login instructions'), and logout. This adds semantic meaning beyond the raw enum, though the term 'get login instructions' could be clearer. With 0% schema description coverage, the description is essential and mostly succeeds.

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 the tool manages Aident MCP authentication and enumerates the specific operations: check status, get login instructions, or log out. This is a specific verb (manage) applied to a clear resource (authentication), and it distinguishes the tool from siblings like audit, billing, or vault, which handle different domains.

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 by listing actions (status, login, logout) but does not provide explicit guidance on when to use this tool versus alternatives or when to avoid it. The second sentence about refreshing SETUP.md is tangential and does not clarify usage. Since no sibling tool overlaps with auth, the lack of explicit exclusions is acceptable, but the guidance remains implied rather than explicit.

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

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

It discloses important behavioral nuances beyond annotations: checkout must happen only after user choosing, refunds require quote and explicit confirmation, and portal/invoices/trial-status are for managing existing accounts. It doesn't describe the side effects or irreversible consequences of a refunds or checkout, so it stops short of complete transparency.

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

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

The description is dense but not bloated. Every sentence adds a meaningful usage rule or behavioral constraint, and the structure moves through actions in logical operational order.

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 most of the main actions and key workflow ordering, but it doesn't fully address all 8 parameters or all output expectations, and there is no output schema to fill that gap. Some actions like portal/invoices/trial-status are grouped generically, so it is adequate but not fully complete for a complex billing 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 schema covers all parameter names/types/descriptions, so the baseline is 3. The description adds practical parameter context by showing the needed refund quote ID must be provided with explicit confirmation and that plans should be consulted before recommending checkout, which is beyond the schema.

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

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

The description clearly explains the billing tool's major purposes: checking balance, comparing plans, creating checkout, refunding, and managing the existing account via portal/invoices/trial-status. It uses specific verbs and action names and gives each action a concrete role, so an agent can tell what the tool covers.

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 explicit when-to-use guidance for each action, including ordering requirements: refund-quote before refund, checkout only after the user chooses, and balance only when the user asks to inspect credits. It also excludes a misuse case by saying not to use balance to do preflight credit checks.

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 discloses execution backends (integration vs Sandbox-local), retry semantics, multi-account selection behavior, and the server's rejection with account-selection-required. Annotations (readOnlyHint: false, openWorldHint: true) are consistent and the description enriches them with concrete operational details.

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

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

The description is front-loaded with the core purpose and then provides necessary operational detail without redundancy. Each sentence contributes guidance for edge cases, making it appropriately sized for a complex execution 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?

For a tool with no output schema and significant complexity around acknowledgements, credit approvals, and multi-account routing, the description covers all invocation scenarios comprehensively. It also clarifies Skill vs Action differences.

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?

Input schema has 100% coverage with detailed descriptions, so baseline is 3. The description adds procedural semantics for acknowledgementScope, approvalToken, and accountAlias (including Skill never accepting accountAlias), which goes beyond the schema's field-level explanations.

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 explicitly states 'Execute a capability by exact name' with a specific verb and resource. It distinguishes from capabilities_search and capabilities_get by focusing on execution rather than discovery/retrieval.

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

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

Provides clear guidance on when to use this tool: after obtaining canonical names from capabilities_search or capabilities_get. It gives explicit pre-steps for side-effecting actions (call capabilities_get for userAccounts), and describes retry flows for acknowledgement and credit approval, plus the accountAlias requirement.

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 indicate readOnlyHint=false and destructiveHint=false, aligning with the write-but-not-destructive nature of reporting feedback. The description adds useful context about what aspects can be feedback (performance, auth friction, search quality), but does not disclose persistence or response behavior, which is acceptable given 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 three sentences, front-loaded with the main purpose and then delivering targeted usage instructions for each targetType. Every sentence contributes value without redundancy.

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

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

With 10 parameters and no output schema, the description covers both main use cases and specific scenarios, while the rich schema descriptions handle the remaining parameter details. It is sufficiently complete for selecting and invoking the tool, though it does not specify return values.

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 baseline is 3. The description adds conditional guidance for targetType values, clarifying when to use 'capability' versus 'search', which helps parameter selection beyond the schema's field-level descriptions.

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 'Report feedback about capability usage or capability search quality', giving a specific verb and resource. It distinguishes two distinct target types (capability vs search), which sets it apart from sibling tools like capabilities_execute or capabilities_search.

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 instructs when to use each targetType: 'Use targetType="capability" after using a capability' and 'Use targetType="search" when the search results were irrelevant...' This provides clear contextual guidance and covers edge cases like unclear instructions or missing schemas.

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 read-only nature is covered. The description adds the constraint that the name must be exact and canonical, which is useful but does not go beyond that—no mention of error behavior, response details, or rate limits. 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 a single, front-loaded sentence that directly states the purpose without any redundancy or filler. Every word contributes to understanding what the tool does.

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

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

Given the tool's simplicity (two parameters, output schema present, read-only annotation), the description covers the core action well. However, it misses a hint that the canonical name is typically obtained from capabilities_search, which would improve the workflow context. Still, the existing schema and annotation cover most needs, so the description is mostly 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%, with both parameters (name and parts) having detailed descriptions including canonical name format, example, and allowed enum values for parts. The tool description itself adds no extra parameter semantics beyond what the schema already provides, so the baseline of 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 clearly states the tool "Get full metadata for a capability" and specifies the input "by exact canonical name," distinguishing it from sibling tools like capabilities_search (which find capabilities) and capabilities_execute (which runs them). The verb and resource are specific and 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?

The description implies usage when you already have the exact canonical name but does not explicitly mention alternatives or when not to use it. For instance, there is no direct guidance to use capabilities_search first to obtain the canonical name, nor any exclusions. The phrase "exact canonical name" offers some context but lacks explicit differentiation.

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 discloses key behaviors beyond the readOnlyHint annotation: it estimates cost, returns approval requirements, and does not execute the Action. This provides useful context about what the tool does and its side-effect-free nature.

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 primary purpose and followed by a specific usage recommendation. Every word earns its place; no redundancy or filler.

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

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

Given the simple input schema and readOnly annotation, the description covers the essential aspects: validation, cost estimation, approval check, and non-execution. It lacks details on return format, but that is not critical for a preflight 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 schema already provides full parameter descriptions, including the exact format for 'name' and the meaning of 'input'. The description adds no new parameter information, but also doesn't need to given the high schema coverage. 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?

The description clearly identifies the tool's function: validate an Action input, estimate credit cost, and return approval requirements without executing. This distinguishes it from siblings like capabilities_execute, making its purpose unmistakable.

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 explicitly states when to use: 'before dynamically priced or metered Actions when the cost depends on input.' The phrase 'without executing it' implicitly guides against using this when execution is desired, making the usage context 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?

With readOnlyHint=true annotation, the safety profile is already established. The description adds a useful behavioral detail about canonical names being returned, which is beyond the annotations. However, it does not elaborate on caching, pagination limits, or result filtering behavior, which are covered in the schema but not synthesized for the agent.

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 two short sentences, with the primary action first ('Search capabilities') and a focused secondary sentence about using results. Every word serves a purpose; there is no filler or 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?

The tool has a rich output schema and detailed parameter descriptions, so the description does not need to explain return values. It effectively captures the core workflow (search, then use canonical name in related tools) and is complete for a search tool given the supporting schemas. Minor gap: it does not mention batching behavior via 'queries' vs 'query', but that is available in the schema.

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 93%, so parameters are well-documented in the input schema. The description itself does not add extra meaning to any parameters; its only added value is the canonical name tip, which relates to output rather than input. This meets the baseline for schema-heavy tools.

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 the tool's function as 'Search capabilities,' which is a clear verb+resource pairing. It also implies a distinction from sibling tools by mentioning that results should be fed into capabilities_get, capabilities_preflight, and capabilities_execute, though it does not explicitly name the alternative to avoid.

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 explicit downstream usage guidance: 'copy the exact returned name into capabilities_get, capabilities_preflight, and capabilities_execute.' This tells the agent when to use the search results and how to connect to related tools. It stops short of saying when not to use search or when to prefer another tool, but the context is fairly 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 indicate readOnlyHint=false and destructiveHint=false, so the tool is a write but non-destructive operation. The description adds the redaction requirement and the triage context, but does not disclose further behavioral traits like post-submission effects, authentication needs, or rate limits. This 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 description is a single, front-loaded sentence with no wasted words. It quickly conveys the action, subject, and purpose in a compact form.

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

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

Given the tool's simplicity (3 params, no output schema, good annotations), the description and schema together provide sufficient context for invocation. The only missing piece is what happens after submission (e.g., response format), but this is not critical for a straightforward submission action.

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 each parameter clearly documented (e.g., report is 'Redacted Markdown bug report with observed and expected behavior...'). The description adds minimal additional parameter meaning, so the baseline score 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 the tool's action ('Submit'), the object ('a redacted Aident Loadout bug report'), and the purpose ('for product triage'). This specific verb+resource+scope effectively distinguishes it from sibling tools like audit, billing, or capabilities_*.

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 provides clear context: it is for submitting bug reports for triage, and the 'redacted' requirement implies appropriate content. While it does not explicitly name alternatives or when-not-to-use, the sibling tool names are distinct enough that the intended usage is unambiguous.

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 are minimal (readOnlyHint false, destructiveHint false), so the description adds important behavioral guidance: rating should be independent of any rating instructions inside the Skill. This is a unique behavioral trait not captured elsewhere. It does not disclose side effects like whether the rating is public or reversible, but the independence note adds significant value.

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 two sentences, front-loaded with the core purpose, and every word earns its place. No redundant or filler content.

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

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

The tool is simple with only three parameters, all fully described in the schema. The description covers the purpose and key behavioral rule (independence from skill instructions). No output schema is present, but the tool's return value is likely trivial and not necessary for correct invocation. Complete enough for an agent.

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 each parameter (skillName, rating, issue) already well-documented in the schema. The description does not add additional semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'rate a public text Skill' with a specific verb and resource. It adds context ('after following it') and distinguishes from sibling tools like skills_read by focusing on feedback rather than reading.

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 a clear context for use ('after following it') but does not explicitly mention alternatives or when not to use it. The 'Optionally rate' phrasing implies the tool is optional, but no direct comparison to sibling tools is 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?

The readOnlyHint annotation already signals a safe read, and the description adds useful context about public text Skills and canonical identity. But it does not disclose behavior for missing skills, return format details, or limitations, so it adds only modest value 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?

Two sentences, front-loaded with the tool's action and scope, and the second sentence provides actionable follow-up guidance. Every sentence earns its place with no redundancy.

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

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

Despite the readOnlyHint annotation, the tool has six parameters, nested objects, and no output schema, and the description does not explain key parameters like parts, paths, or traversal. It is adequate for a simple read but notably under-specified for correct invocation of all available options.

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?

With 0% schema description coverage, the description carries the burden for explaining the six parameters, but it only clarifies 'name' as canonical identity and 'optional revision' (likely artifactRevision). It leaves parts, paths, traversal, and artifactVersionId unexplained, which is a significant gap given the nested schema.

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

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

The description uses a specific verb ('Read') and resource ('full entrypoint and manifest for one public text Skill'), and clarifies that selection is by 'exact canonical identity' with 'optional revision.' It does not explicitly contrast this with sibling tools like skills_feedback or capabilities_search, so sibling differentiation is mostly 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?

The description implies usage when you need to read a known Skill by canonical identity, and it provides concrete follow-up guidance to optionally call skills_feedback. However, it does not explicitly state when to use this tool instead of alternatives, nor does it mention exclusions or prerequisites beyond exact identity.

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 annotation readOnlyHint=false already signals mutating behavior. The description adds minimal behavioral context beyond listing the actions, which are also present in the action enum. It does not disclose side effects, OAuth flow requirements, the need for confirmation flags (e.g., replaceAccountConfirmed), or the guidance that agents should send connectUrl to users rather than request secrets. Given the complexity of the tool, this is a significant gap.

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 a single, efficiently worded sentence that front-loads the purpose and enumerates the key actions. Every word contributes value with no redundancy or 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?

The tool has 10 parameters, nested objects, and no output schema, yet the description provides only a high-level summary. It omits critical operational details such as how OAuth connection works, the distinction between reconnecting and adding a new account, confirmation requirements, and expected return values. The schema hints at some of this, but the description alone is insufficient for an agent to invoke the tool correctly in complex scenarios.

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 high (90%), and each parameter has a descriptive explanation (e.g., accountAlias, confirmed, addAccount). The description itself adds no parameter-level meaning. Baseline 3 is appropriate because the schema carries the semantic load.

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 the tool's purpose: 'Manage Loadout Vault connections: check status, connect, or disconnect integrations.' It uses a specific verb ('manage') and resource ('Loadout Vault connections'), and lists the three primary actions. This distinguishes it from sibling tools like auth or capabilities_execute, which handle different resources.

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 a clear usage context: it is the tool for managing Vault connection lifecycle. However, it does not explicitly state when not to use it or reference alternative tools. Since the scope is clearly defined as check/connect/disconnect, the context is sufficient without explicit exclusions.

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