Spellwarden

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose a real side effect beyond the schema — that adding a server 'starts its first scan' — which is valuable and non-obvious. It does not state what happens on duplicate adds, whether the scan is synchronous or how long it takes, or what permissions are required for this mutation.

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 the three input modes, closed by the exclusivity rule. No filler and nothing repeated from the schema field descriptions.

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 annotations and no output schema, the description covers how to identify a server and that a scan is triggered, but omits return value (added server object, scan identifier), error/duplicate behavior, and the auth implications only partially covered by the organisation parameter text. An agent could call it but could not anticipate the response.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: it declares that exactly one of endpoint/repo_url/registry_name must be supplied, whereas the schema lists all five as optional with an empty required array. It also ties repo_url to the stdio server type, a semantic link the schema only hints at.

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 ('Adds an MCP server') and enumerates the three supported identification modes: endpoint URL, repository URL (explicitly flagged as a stdio server), and registry name. This is clearly distinct from read-side siblings such as list_mcp_servers and list_registry_entries, 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?

'Pass one of the three' establishes mutual exclusivity, which is genuine usage guidance absent from the schema (required is empty). However, it gives no guidance on which of the three modes to prefer for a given situation, no prerequisites (auth, organisation scoping), and no when-not-to-use conditions such as an already-registered server.

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 no annotations present, the description carries the full burden; it does usefully disclose the zip packaging and that the download link expires in 15 minutes, which an agent cannot infer elsewhere. It is silent on permission requirements, whether exports are billed or size-limited, and whether repeated calls regenerate new links.

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 front-loaded sentence that moves from action to contents to platforms to return value with no filler. The three-platform list makes it dense but each token 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?

It covers the return contract even without an output schema and names the export targets, but for a tool with a nested object parameter and organisation-scoped access it omits auth expectations and any constraint on combining source with target. Adequate rather than 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 four parameters are already documented, including enum meanings and the nested dataset shape. The description adds no parameter-level meaning beyond restating that practice variants bundle tasks and that a tool dataset may be included.

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

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

States a specific verb and resource ("Exports an eval rubric") plus the artifact contents (practice tasks or an MCP server's tool dataset), the output format (zip), the three destination platforms, and the return value. An agent can distinguish it from export_policy_pack purely from the description.

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 by the enumerated destination platforms; the description never says when to choose this over export_policy_pack or what preconditions must hold. The useful routing constraints ("Tool descriptions go to foundry only; agent sessions not to claude-outcomes") live in the schema, not the description.

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 no annotations, the description carries the behavioral burden and does well: it discloses that the result includes a download link that expires after 15 minutes, and that only a *published* version can be exported. It does not discuss permission requirements or what happens on failure, but the key temporal constraint is surfaced.

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

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

Three compact sentences, front-loaded with purpose then parameter behavior, with no filler. Every clause (expiry window, version default, mode semantics) 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 5-parameter export tool with no output schema, the description covers what is returned (an export plus a time-limited download link) and the two enum-driven behaviors. It omits any note on output format or whether the export is generated synchronously, which would be the remaining gap.

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

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

Schema coverage is already 100%, so baseline would be 3, but the description adds meaning the schema doesn't: default-to-latest behavior for version, the baseline pack's version 1.0, and the project-vs-managed distinction for Claude Code (repository files vs administrator-installed files). That materially improves correct invocation.

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 ('Exports a published policy pack version') and enumerates the concrete targets (Claude Code hooks, Kong, Zuplo), which no sibling tool covers. An agent can immediately tell this apart from list_policy_packs or export_eval.

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

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

It gives real selection context: the version parameter is optional with a latest-by-default rule, the baseline pack maps to 1.0, and mode is only meaningful for Claude Code. It stops short of explicitly naming alternatives (e.g. 'call list_policy_packs first to obtain pack_id'), so the routing guidance is clear but not exhaustive.

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

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

With no annotations, the description must carry the behavioral burden, and it does disclose two useful traits: runs are long-lived (minutes, implying repeated polling) and results are informational rather than actionable. It omits failure behavior for unknown run_ids and any indication of what the returned progress fields contain.

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

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

Two short sentences with the primary scope constraint front-loaded and no filler. The trailing clause about results being informational is slightly vague but still carries signal, so it 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 two-parameter getter with no output schema and no annotations, the description should say more about the returned progress object, such as status values or completion indicators. It is adequate but leaves the agent guessing about what to inspect while polling.

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 both run_id and organisation are already well documented in the schema, including the OAuth/API-key scoping nuance. The description adds no further meaning about run_id, 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 uses a specific verb and resource ("Returns one eval run and its progress") and carves out scope with "without the task rows", which separates it from a fuller retrieval. It does not name a sibling such as start_eval_run or export_eval to sharpen the distinction, 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?

Usage is only implied: the "without the task rows" clause suggests a heavier variant exists, and "eval runs take minutes" hints at polling for status. There is no explicit statement of when to call this versus start_eval_run or export_eval, and no stated preconditions.

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

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

With no annotations, the description carries the full burden, and it does disclose what the operation returns, including the scope of findings (open and accepted manual findings) and the deadline metric. It does not address permissions, caching, or whether the scan is triggered or merely reported, which is why it falls short of a 5.

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

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

A single front-loaded sentence with no filler; every listed element corresponds to something the caller receives. The comma-separated enumeration is slightly dense and could be broken into a clearer structure, 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?

There is no output schema, so the description must convey the return shape, and it does so by naming the report's components. For a two-parameter read tool this is nearly complete, with only the absence of usage context keeping it below a 5.

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

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

Schema description coverage is 100%, and the schema already explains both server_id and the subtle organisation fallback in detail. The description adds no parameter-level meaning beyond that, 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 uses a specific verb and resource ('Returns a server's migration report') and enumerates the report's contents: classification, latest scan findings, ordered checklist, and days to the MCP deprecation deadline. That enumeration distinguishes it from neighbours like list_findings or get_trust_score, 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?

No when-to-use or when-not-to-use guidance is given, and no prerequisites are stated. The purpose implies usage (checking migration status before the deprecation deadline), but the agent must infer that context rather than being told.

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 no annotations, the description carries the full burden and does disclose meaningful behavior: the exact response payload, the caller's own identity, and the connection's grant including whether it is read-only or read-write and how to change it. It omits auth requirements, failure modes, and rate limits, so it stops short of a 5.

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

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

A single front-loaded sentence that opens with the verb and resource, then lists return fields. It is dense and every clause carries information, though the trailing parenthetical about the grant makes the sentence long and slightly hard to parse on first read.

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?

Zero required parameters, no output schema, and the description compensates by enumerating the returned fields — precisely what an agent needs in the absence of a return schema. The schema covers the one input, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single optional parameter is documented thoroughly in the schema, including the OAuth/API-key default and the legacy multi-org exception. The description itself adds nothing about the parameter, 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?

Uses a precise verb ('Returns one organisation') and then enumerates exactly what that single record contains: slug, name, plan, billing state, member count, SSO status, caller identity, and grant scope. An agent can immediately distinguish it from the plural sibling list_organisations.

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 states no when-to-use, when-not-to-use, or alternative. The real routing guidance lives in the parameter schema ('from list_organisations', 'Leave it out...'), not the description, so usage is only implied by the singular-vs-plural naming.

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 no annotations, the description carries the full burden and does reasonably well: it discloses the data source (OpenTelemetry traces and events), the metrics returned (calls, errors, latency), and that the operation is read-only and does not affect scores. It omits trace-ingestion lag, empty-result behavior when no telemetry exists, and pagination, which are meaningful gaps for a telemetry-backed list.

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

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

A single dense front-loaded sentence enumerates the entity kinds and metrics, followed by a short clause on the informational nature. No filler, though the enumeration is long enough that the core purpose ('lists runtime inventory from OTel telemetry') competes with the detail.

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 three-parameter read tool with no output schema, the description conveys both input scope (entity kinds, metrics, cross-referencing to Spellwarden) and the nature of the result well enough to call it correctly. It stops short of describing result grouping or empty-state behavior, which leaves a small gap given there is no output 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 coverage is 100%, so all three parameters are already documented in the schema, including the enum values for kind and days and a detailed explanation of organisation/OAuth scoping. The description restates the kind enum values without adding format, default, or interaction semantics beyond that. Baseline 3 applies.

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

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

States a specific verb and resource (lists runtime-used MCP servers, tools, skills, models, agents, decisions, services) and names the data source (OpenTelemetry traces and events) plus the enrichment (matching against what Spellwarden knows). It implicitly separates itself from registry-style siblings like list_mcp_servers and list_skills by being about observed runtime usage, but it never names those siblings 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?

The clause 'Informational: it changes no score' rules out a scoring use case, which is useful guidance. However, there is no explicit statement of when to prefer this over list_mcp_servers or list_skills, no prerequisites, and no exclusions beyond the scoring note.

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 no annotations, the description carries the burden and does meaningful work: it discloses the composite return shape (skill + latest scan + its findings), the finding filter (open and accepted manual findings), and the ordering (severity first). It omits permissions/auth behavior and what happens when no scan exists, but the key behavioral traits are covered.

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?

One sentence, front-loaded with the verb and resource, no filler. The trailing "and that scan" clause is awkward and would be clearer as a 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?

No output schema exists, so the description must explain the return value, and it does so at a useful level of detail, including which findings are included and their ordering. Minor gaps remain around empty/no-scan cases and pagination of findings, but the tool's core is adequately specified.

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 skill_id and organisation parameters are thoroughly documented in the schema, including the OAuth/API-key scoping caveat. The description adds no parameter semantics of its own, so baseline 3 applies.

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

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

States a specific verb and resource ("Returns one skill") and enumerates what comes with it: latest-scan findings, open and accepted manual findings, and the scan itself. That separates it from list_skills, though it never names the sibling explicitly and the final clause ("and that scan") is grammatically tangled.

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 and no alternatives named. An agent must infer from the required skill_id that this is the single-record fetch counterpart to list_skills; nothing addresses when to prefer list_findings or get_trust_score instead.

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

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

With no annotations supplied, the description carries the full burden, and it does disclose meaningful behavior: the exact composition of the score and the caveat that Eval coverage is displayed but not yet weighted into the total. That caveat prevents a real misinterpretation of the returned number. It stops short of 5 because it says nothing about permissions, freshness/caching, or whether the score is computed live.

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, no filler, with the core purpose front-loaded and the caveat placed immediately after the component it qualifies. Every clause earns its place.

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

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

For a zero-required-parameter read tool with no output schema, the description is nearly sufficient: it names the returned components so the agent knows roughly what comes back. It does not describe the shape of the response (e.g., whether components are numeric scores or nested objects), which is the only remaining gap.

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

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

Schema description coverage is 100% and the single optional "organisation" parameter already has a thorough description covering the slug source and the OAuth/API-key default behavior. The tool description adds nothing about the parameter, so the schema does all the work and 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?

"Returns the organisation's trust score" is a specific verb+resource, and the description further decomposes the score into Security, Migration, Eval coverage, and the count of assets with accepted critical/high risk. It does not distinguish itself from siblings like get_migration_report or list_findings, which supply some of the same underlying data, 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?

Usage is only implied: the enumeration of score components suggests this is the high-level overview tool, but the description never says when to prefer it over get_migration_report, get_eval_run, or list_findings. There are no explicit when-not conditions or alternative routing.

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

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

No annotations exist, so the description must carry the behavioral load. It does disclose that results include status and last sync, and 'Lists' implies a read-only, non-destructive operation, but it says nothing about permissions, pagination, ordering, or what an empty result means.

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 front-loaded sentence that names the resource and the returned fields with no filler. Every clause earns its place.

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

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

With one optional, fully documented parameter and no output schema, the description is close to sufficient; the return fields are briefly characterized. It falls short only on pagination/ordering behavior and on how 'connected' spaces relate to other org-scoped listing tools.

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

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

Schema coverage is 100% and the schema's own description of 'organisation' is unusually thorough, explaining OAuth/API-key scoping and when the parameter can be omitted. The description adds nothing beyond that, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Lists the AWS DevOps Agent Agent Spaces connected to the organisation') and names the returned fields (status, last sync). It is clearly distinct from siblings like list_organisations or list_mcp_servers, though it never explicitly routes the agent away from them.

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 in the description; it does not say whether this is the right call for checking connectivity versus, say, list_organisations. The only usage framing appears in the parameter schema, not the description 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?

With no annotations, the description carries the full burden and does disclose the important behavioral facts: which fields come back and that key material is never returned, which is a genuine security-relevant guarantee. It stops short of stating permissions required, pagination behavior, or explicitly that the operation is read-only, which keeps it from a 5.

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

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

Two short clauses, front-loaded with the resource and followed by the most decision-relevant fact. Every word earns its place, including the terse 'Never the keys' caveat.

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-optional-parameter read tool with no output schema and no annotations, the description covers both the field-level return shape and the security boundary, which is what an agent most needs. Minor omissions like pagination and permission requirements are acceptable at this 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%, and the schema already explains both the optional organisation slug and the include_revoked default in detail. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists an organisation's API keys') and enumerates the returned fields (name, access, last four characters, dates). The closing 'Never the keys' pins down exactly what this tool is not, so an agent can distinguish it from any secret-retrieval expectation without opening the schema.

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

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

There is no explicit when-to-use statement or named alternative, but the tool's role is implied by the read-only listing framing and the 'Never the keys' note, which signals it is safe for inspecting key metadata without exposing secrets. No sibling covers API keys, so the absence of routing guidance is a smaller gap than it would otherwise be.

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 no annotations supplied, the description carries the full burden and does disclose some real behavior: results are limited to the latest scan (no history), ordered newest first, and default-include open and accepted manual findings. It leaves material gaps, though: it never says how the status filter interacts with that default (does status=fixed override it?), says nothing about pagination despite a cursor param, and says nothing about permissions or volume 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 sentence, front-loaded with the verb and resource, with no padding or marketing language. It is a long run-on that packs ordering, scope and defaults together, which costs a little parseability, 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?

Seven optional parameters, no annotations and no output schema mean the description must define both the result set and, ideally, what a finding looks like. It defines the result set adequately (latest scan, newest first, open and accepted manual) but says nothing about returned fields or pagination behavior, leaving an agent unsure what it will receive.

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 57%, with origin and target_id well documented and the four enums largely self-describing, so the schema does most of the work. The description adds no parameter meaning at all beyond the word "filters" and does not clarify the status enum's default, which is exactly where the coverage gap sits. It neither compensates for the gap nor contradicts it.

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

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

Specific verb and resource: "Lists the findings" scoped to "the latest scan of every skill, MCP server and repository", plus the manual-findings case and the "newest first" ordering. No sibling tool in this server lists findings, so it is distinguishable by default. The only drag is the tangled clause "and their open and accepted manual findings", which reads as both scope and default filter, making the resource boundary slightly fuzzy.

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 mention of "latest scan" plus "open and accepted manual findings" hints at the default result set, and "with filters" signals the optional narrowing parameters. There is no explicit when-to-use, no when-not, and no pointer to get_skill / list_skills for the underlying skill or server detail. An agent can guess reasonable use but is given no routing 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?

No annotations are provided, so the description carries the full burden; it does disclose the returned attributes (classification, auth mode, finding counts), which is real behavioral value. It says nothing about pagination despite a cursor parameter, nor about ordering, result volume, or whether the call is safe/non-mutating beyond the word 'Lists'.

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 front-loaded sentence with no filler; the returned-attribute list is informative rather than redundant. It is appropriately sized for a two-parameter read tool, though it could have traded a few words for a routing hint.

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 list tool with no output schema and fully documented parameters, the description covers purpose and return contents adequately. The main gap is pagination behavior, which an agent must infer from the cursor parameter alone.

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 organisation parameter is documented in unusual depth in the schema itself, including OAuth/API-key scoping. The description adds no meaning beyond the schema, 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?

States a specific verb (Lists) and resource (the organisation's MCP servers) and even names the returned attributes: classification, authentication mode, finding counts. It implicitly separates from add_mcp_server by being the read side, but never names a sibling or scope boundary 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 by the name and by the absence of any other list tool for MCP servers among the siblings. There is no explicit when-to-use, no statement of when the tool is not appropriate, and no mention of the connection/permission context that the schema's organisation parameter hints at.

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 no annotations supplied, the description carries the full burden and delivers: it explains that the connection's grant determines scope, distinguishing OAuth sign-in (one person, one organisation, read-only or read-write) from API key (one organisation). The access-level semantics are exactly the kind of context an agent cannot get from structured fields. It does not mention result size or pagination, a minor gap for an unbounded list.

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 operation and its return fields, then the call-order instruction, then the access model. No filler. The final sentence about API keys is slightly compressed but still 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 zero-parameter list tool with no output schema, the description covers what comes back, when to call it, and what governs the result set. The only omission is anything about result cardinality or ordering, which is minor here.

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

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

The tool takes zero parameters, so the baseline is 4 and the description correctly does not waste words on nonexistent inputs. It instead spends that space on the grant semantics, which is the right allocation.

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?

Opens with a specific verb and resource ("Lists the organisations this connection reaches") and enumerates the returned fields: slug, name, plan and billing state. The plural scope distinguishes it cleanly from the sibling get_organisation.

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?

"Call it first" gives explicit sequencing guidance that no sibling tool provides, which is genuinely useful for orienting an agent. It stops short of saying when not to call it or pointing at get_organisation for detail, so it is strong but not exhaustive.

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

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

No annotations are supplied, so the description carries the burden alone. It does usefully disclose the return shape (latest version, enforcement and org rule counts) and a deterministic ordering contract, which is real behavioural value. It does not mention pagination, permissions, or side-effect profile, which a no-annotation definition ideally would.

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?

One sentence, front-loaded with the verb and resource, and every clause carries information the agent would otherwise have to discover by calling. The trailing clause is dense but not padded; no wasted wording.

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 optional parameter, no annotations, no output schema), and the description compensates for the missing output schema by describing what each entry includes and how entries are ordered. Only the absence of any guidance on volume or pagination keeps this from a 5.

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 optional `organisation` parameter is explained there in detail, including OAuth and API-key scoping. The description adds only the possessive "the organisation's" and no syntax or default guidance beyond the schema, 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 opens with a specific verb and resource ("Lists the organisation's policy packs") and even names the ordering rule (Spellwarden baseline first), which lets an agent tell it apart from the other list_* siblings without opening the schema. It stops short of explicitly naming a sibling for contrast, but no sibling covers policy packs, so the ambiguity risk is low.

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 by the verb "Lists"; there is no explicit statement of when to call this versus export_policy_pack or get_organisation, and no prerequisites or exclusions are given. An agent can infer this is the discovery step, but it has to do that inference 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?

With no annotations, the description carries the full burden. It discloses the enterprise-plan restriction and that the registry is private and includes admitted skills/servers, but it omits details like pagination behavior, read-only nature, and return format. Some useful behavioral context is provided, though gaps remain.

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 core purpose and followed by the key restriction. There is no unnecessary wording; every sentence 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 simple list tool with fully documented optional parameters and no output schema, the description covers what is listed and the plan restriction. It could mention pagination or return shape, but the schema already handles cursor semantics, so the description is largely 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 the input schema already fully documents both parameters. The description adds no parameter-specific meaning beyond the schema, which is the baseline expectation when coverage is high.

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

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

The description states a specific verb ('Lists') and resource ('organisation's private registry and the skills and servers it admits'), making the tool's purpose clear. It does not explicitly differentiate from sibling tools like list_mcp_servers or list_skills, 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 phrase 'Enterprise plan only' gives one usage condition, but there is no guidance on when to choose this tool over alternatives such as list_mcp_servers or list_skills. Usage is implied rather than explicitly contrasted with siblings.

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

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

No annotations are supplied, so the description carries the disclosure burden. It does reveal output content (scores, curation state, findings) which is valuable given there is no output schema, but it says nothing about pagination ordering, result limits, or whether the scan data is fresh — real behavioral gaps for a no-annotation 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?

A single sentence, front-loaded with the verb and resource, with the returned attributes appended. Nothing is wasted, though the tail clause listing three attributes reads slightly as a run-on rather than a clean structure.

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

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

For a paginated list tool with no annotations and no output schema, the description gives a partial picture of the return shape but omits pagination behavior and result ordering. It is adequate to select the tool but not fully sufficient to predict its behavior.

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 a detailed note on when the organisation parameter is needed, so the schema already does the heavy lifting. The description adds no parameter-level meaning beyond what is documented in the schema; baseline 3 applies.

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

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

States a specific verb and resource (lists scanned skills) and names the salient returned attributes — curation score, Curated/Quarantined state, open findings — so the agent knows what the call yields. It does not explicitly contrast itself with siblings like get_skill or list_findings, but the list-vs-get distinction is clear from the name and wording.

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 description frames it as an enumeration of the organisation's skills, which suggests it is the entry point before drilling into get_skill. There is no explicit when-to-use / when-not-to-use statement and no mention of paging through results via cursor, so the agent must infer from 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?

With no annotations, the description carries the full burden and does disclose the key trait: the operation is asynchronous, returning a queued scan rather than a completed result, and it enumerates the terminal statuses (passed, failed, incomplete, error) that end the polling loop. It omits idempotency, permission requirements, and failure behavior on unparseable repos.

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, zero waste: the first establishes the action and return value, the second gives the polling instruction. The critical information is front-loaded.

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, describing the return as 'the skill and the queued scan' plus the terminal statuses is enough for an agent to complete the start-then-poll workflow. The remaining gap is that no description explains what a scan actually inspects, which a caller may want when deciding to invoke it.

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 url, ref, path and organisation are already documented in the schema, including the conditional guidance for organisation. The description contributes only the constraint that the URL must point at a public GitHub or GitLab repository, which the schema also states, so 3 is the appropriate baseline.

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

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

States a specific verb and resource ('Starts a scan of a skill'), scopes it to 'a public GitHub or GitLab repository', and names both halves of the response payload. The follow-up sentence separates this tool from get_skill, which the agent is told to use for reading results.

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 'public' qualifier implicitly excludes private repositories, and the description explicitly routes result-reading to get_skill until a terminal status is reached. It stops short of stating preconditions such as authentication or what to do if a scan is already queued for the same ref.

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 no annotations, the description carries the burden and does well: it discloses the async/background model, the queued return state, the polling contract, quota consumption (20/month, 3 trial) and that results are informational and do not change scores. Gaps remain on what happens when the quota is exhausted or how a run fails, but the core behavioral profile is unusually well covered.

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 action and return state, then the polling instruction, then cost and side-effect caveats. Every sentence adds distinct information with no repetition of the name or 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 7-parameter asynchronous mutation with no annotations and no output schema, the description covers the lifecycle and the cost model well. It stops short of saying what the queued return contains (e.g. the run identifier needed for get_eval_run), which matters since no output schema documents the response shape.

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

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

Schema description coverage is 100%, so every parameter including the required idempotency_key, the kind enum, suite_id, server_id and skill_ids is already well documented in the schema. The description adds no parameter-level meaning beyond noting the run counts against quota; 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 ("Starts an eval run") plus the execution mode ("in the background and returns it queued"), and names the sibling get_eval_run as the follow-up reader. An agent can tell instantly that this is the async kick-off call rather than a read or export.

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

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

Gives clear usage context: start here, then poll get_eval_run until status is finished, invalid or error. It does not explain when to choose which run kind (paired vs tool_grades) — that is left to the enum description — and states no when-not-to-use conditions beyond the implicit quota limit.

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