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

Beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false), the description explains per-action behavior: inspect reads settings/schema/choices, preview validates without saving, apply persists only a token-bound user-approved preview, verify checks active targets. It also adds operational behavior (restart after changes) and a security constraint (never send credentials).

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 efficiently front-loads the main purpose before detailing each action. Semicolon-separated action clauses are compact, though the single paragraph packs multiple concepts together rather than using clearer structure.

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

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

With an output schema present, return-value documentation is not needed, and the annotations cover the tool's safety profile. The description supplies the workflow, action semantics, approval/token requirements, restart need, and security constraint, making it complete for correct invocation.

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

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

Schema description coverage is 100%, and the schema already defines action, patch, approved, and confirmation_token in detail. The description reinforces the action flow and approval/token usage but adds little syntactic or semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description specifies a setup and guidance resource ('self-contained WhoDB MCP guidance and setup') and enumerates the four actions, giving a clear verb+resource. It does not explicitly differentiate itself from the many whodb_platform_* siblings by name, but the 'start here' framing and action breakdown make the purpose identifiable.

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 provides clear workflow guidance: begin with inspect, preview before apply, apply only after user approval, restart after changes, and never send credentials. It does not name alternative tools or explicit exclusions beyond 'without skills or shell access', but the sequencing and guardrails substantially reduce misuse risk.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the preview/confirmation-token gate, the requirement to obtain user approval before confirming, the warning that some actions mutate hosted resources, and platform-enforced permission checks. It does not describe the shape of the returned confirmation token or action result.

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

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

The purpose is front-loaded and each subsequent sentence carries operative information: supported actions, the schema resource to consult, the confirm gate, and workspace targeting. The dense action enumeration is long, but for a catch-all dispatcher it materially helps an agent decide whether the action exists here rather than being pure 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?

For a seven-parameter dispatch tool with no output schema, the description covers the essentials: what actions exist, where to find payload shapes, the id/payload calling convention, the two-step confirm workflow, permission enforcement, and per-call workspace targeting. The main gap is the absence of return-value or continuation detail (e.g., how the confirmation token is used), though the sibling whodb_platform_confirm partly compensates.

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 seven parameters are already documented, making 3 the baseline. The description adds one concrete detail beyond the schema (for file/upload, payload_json requires file_path and may include folderId), but it also tells callers to 'Pass id and payload_json' while the schema marks payload_json as legacy and says to prefer payload — a mild inconsistency that offsets the added value.

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 clear verb+resource ('Run a hosted platform resource action through the selected project') and then enumerates concrete action names across resource types, so an agent can confirm whether an action is routed through this tool. It stops short of differentiating from dedicated siblings like whodb_platform_create, whodb_platform_delete, whodb_platform_update, or whodb_platform_restore, which cover overlapping operations.

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 workflow sequencing: read whodb://platform/schema for payload shapes, default mode returns a confirmation token, and whodb_platform_confirm must not be called until the user approves the preview. It also notes that permission checks are enforced server-side. What is missing is any explicit statement of when to prefer the dedicated create/delete/update/restore tools over this generic dispatcher.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds a useful behavioral detail — the workspace override is scoped to this call and leaves defaults untouched. It does not disclose what is returned when no active version exists or any access requirements.

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

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

Two compact sentences, front-loaded with the core action and followed by the targeting caveat. No filler and nothing that could be trimmed without losing meaning.

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 tool with full schema coverage and no output schema, the description covers the action and scoping adequately. It leaves open what the returned version payload looks like and how a missing active version is surfaced, which an agent would benefit from knowing.

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

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

Schema description coverage is 100%, so the schema already documents id, fields, object_type, and the nested workspace object. The description's mention of workspace targeting without changing defaults is already present in the schema's own text, so it adds little beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb (read) and resource (active production version of one versioned object), which is enough to distinguish it from listing siblings like whodb_platform_object_versions. However, the description never references those siblings by name, so the differentiation is implicit rather than explicit.

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 explains the per-call workspace targeting mechanic (host/org/project without changing defaults), which is partial usage context. It gives no when-to-use vs alternatives guidance, e.g. versus whodb_platform_object_versions or whodb_platform_project_active_versions, and no prerequisites or failure conditions.

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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: the two-step preview/confirmation-token flow and the rule that confirm is gated on user approval, which is real operational context.

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

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

Three short sentences, front-loaded with the core action before the confirmation workflow and workspace targeting. No filler, though the workspace sentence overlaps material the schema already states.

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 mutating tool with full annotation coverage and 100% schema description coverage, the description fills the key gaps: the preview/confirm gate and default-vs-per-call targeting. The unmentioned update_columns parameter is adequately explained by the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, including the workspace sub-object and its default-semantics notes, so the schema already carries parameter meaning. The description's restatement that values are keyed by property and that workspace targets per-call without changing defaults mostly echoes structured data, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Add one row to a hosted ontology backing table.' Clear enough for an agent to identify the operation, but it does not explicitly differentiate from the sibling whodb_platform_add_ontology_records (bulk-add), leaving that distinction to the tool name alone.

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

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

Gives concrete workflow guidance: default mode returns a confirmation token and confirm must not be called until the user approves the preview, plus the condition for per-call workspace targeting. It does not name the singular-vs-bulk alternative explicitly, so a routing 5 is not warranted.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: the default preview/confirmation-token flow with the confirm gate, the retry-safety semantics of idempotency_key, and the fact that workspace targeting does not mutate session defaults.

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

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

Four short sentences with the core action front-loaded and no filler. Dense but each sentence carries a distinct instruction (shape of rows, idempotency, confirm gate, workspace override).

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

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

No output schema exists, and the description compensates by explaining that the default mode returns a confirmation token, plus the idempotency and targeting behavior. Covers what an agent needs to call it correctly, though it omits any hint on batch-size limits or partial-failure 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%, so the baseline is 3. The description largely restates the schema ('rows are plain objects keyed by ontology property', idempotency_key avoids double inserts) and only adds the minor nuance that workspace is per-call without changing defaults, which the schema already states.

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

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

States a specific verb and resource ('Add many rows to a hosted ontology') and scopes it with 'in one call', which cleanly separates it from the singular sibling whodb_platform_add_ontology_record. An agent can tell which tool to reach for without opening either schema.

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

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

Gives conditional guidance on when to pass idempotency_key and gates the follow-up call ('do not call whodb_platform_confirm until the user approves the preview'). It implies bulk use via 'many rows ... in one call' but never explicitly names the single-row sibling as the alternative, so selection guidance is contextual 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety/read profile is covered. The description adds that per-call workspace targeting does not mutate defaults, which is genuine behavioral context, though it partly duplicates the schema note on host. Nothing is said about pagination, result limits, or auth requirements, so a 3 is fair.

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

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

Two compact sentences with zero filler: the read purpose is front-loaded, followed immediately by the per-call targeting behavior. Every clause carries information.

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

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

For a simple read-only listing tool with full schema coverage and annotations that encode the safety profile, the description covers purpose and workspace targeting adequately. It could be slightly more complete by indicating what a model name/value looks like or that a provider_id must be obtained first, but no output schema exists and none is strictly needed.

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 nested workspace object (host/org/project) is fully documented in the schema itself, including the note that host does not change the default. The description adds no syntax or constraint detail beyond the schema, so the baseline 3 applies. It does not clarify provider_id accepted formats.

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

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

States a specific verb+resource ('List model names') scoped to 'one hosted AI provider', which is enough to separate it from the sibling whodb_platform_ai_providers. It stops short of explicitly naming that sibling as the provider-listing alternative, so it is clear but not sibling-differentiating.

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 sentence 'Accepts workspace {host, org, project} for per-call targeting without changing defaults' describes parameter behavior rather than when to pick this tool. Usage is only implied: an agent infers it should first resolve a provider_id (likely via whodb_platform_ai_providers) and then list models. No exclusions or alternatives are given.

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

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

Annotations already establish readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description nonetheless adds two genuinely useful behavioral facts beyond them: the guarantee that provider API keys are never returned (a security/return-shape boundary worth stating), and that passing workspace targets only that call without mutating session defaults. It stops short of describing result shape or pagination behavior.

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

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

Three short sentences, no filler, and the core action is front-loaded before the filter hint and the caveats. Each sentence carries a distinct load: purpose, filter guidance, secret-exclusion plus targeting semantics.

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 optional parameters, a nested workspace object and no output schema, the description covers the two things an agent could get wrong: it will not leak API keys, and workspace overrides are per-call only. It omits pagination/fields behavior, which matters for a list tool with limit/offset, but the core call-time contract is present.

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

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

Schema description coverage is 100%, so every one of the 10 parameters is already documented in the schema and the baseline is 3. The description echoes the name/type filters and the workspace targeting but adds no syntax, format, or defaulting detail the schema does not already contain.

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

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

The description gives a specific verb and resource: "List hosted AI provider metadata in the selected project." An agent knows exactly what it gets back in kind (provider metadata, not models or keys). It does not, however, differentiate itself from the adjacent sibling whodb_platform_ai_provider_models, which is the one tool an agent is most likely to confuse it with.

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

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

"Use name and type filters when known" is the only usage steering, and it addresses filter usage rather than tool selection. There is no stated condition for choosing this over whodb_platform_ai_provider_models, nor any exclusion or prerequisite. Usage is implied by the purpose statement but never made 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that workspace targeting is per-call and leaves session defaults untouched, which is meaningful behavioral context, but it says nothing about what the 'generated definition' contains or how the detail/files/version views differ.

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 tight sentences with zero filler, and the core purpose is front-loaded before the workspace note. The second sentence is arguably the weaker half since it duplicates schema content, but nothing is padded.

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-only inspection tool with no output schema, the description covers the main case adequately and correctly points at the workspace/session-default resolution chain. It leaves gaps around the multiple view modes hinted at in the id parameter ('detail, files, or version view') and the optional 'fields' output projection, which the description never mentions.

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

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

Schema description coverage is 100%, so the baseline is 3; every parameter including the nested workspace object is documented in the schema itself. The description's workspace sentence largely restates the schema's own workspace description ('Optional target for this call only. Omit to use the session default...'), adding no syntax or format detail beyond 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?

States a specific verb and resource: 'Inspect one hosted app, including its generated definition.' This clearly separates it from the plural listing sibling whodb_platform_apps. It does not distinguish it from near-neighbors like whodb_platform_app_view, whodb_platform_app_version_view, or whodb_platform_app_files, which the schema's 'detail, files, or version view' phrasing suggests overlap with.

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

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

The second sentence explains per-call workspace targeting, which is parameter guidance rather than tool-selection guidance. No when-to-use or when-not-to-use conditions are given, and no sibling (e.g. apps for listing, app_version_view for version history) is named as an alternative, so usage is only implied by the verb 'Inspect one'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one useful behavioral note — the workspace argument applies per call 'without changing defaults' — which clarifies it does not mutate session state the way whodb_platform_session_use does. No detail on missing-name behavior or whether the lookup is case-sensitive.

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

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

Two short, front-loaded sentences with no filler; the purpose leads and the scoping caveat follows. The second sentence largely duplicates what the workspace schema description already states, which is the only small inefficiency.

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

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

For a simple read-only lookup with full schema coverage, full annotations, and no output schema, the essentials are present — what it retrieves, the required category source, and how to target a workspace. The one remaining gap is that 'exact usage' is never unpacked, so the agent cannot anticipate the returned 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% and the nested workspace object is already fully documented, including that it is per-call only and how to discover targets. The description restates {host, org, project} and the no-default-change rule, which the schema already conveys, so it adds little beyond the 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 ('look up') and resource ('exact usage for one app component category'), and explicitly ties it to the plural sibling whodb_platform_app_components, so an agent can distinguish list-vs-detail without opening a schema. The phrase 'exact usage' remains a bit abstract about what is actually returned, keeping it below 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?

Referencing the sibling as the source of the category implies a list-then-detail workflow, which is genuine implicit guidance. However, there is no explicit statement of when to prefer this over whodb_platform_app_sdk, whodb_platform_app_sdks, or the singular whodb_platform_app, and no note on what to do if the name is unknown.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the safety and idempotency profile. The description adds that workspace targeting is per-call without changing defaults, which is useful behavioral context beyond annotations, but doesn't describe output structure, pagination, or rate 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?

Three concise sentences, front-loaded with purpose, followed by usage guidance and a parameter note. No waste, well-structured.

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?

Covers purpose, a usage trigger, and per-call workspace behavior. For a read-only list tool with rich annotations and full schema coverage, this is nearly complete. Missing minor details like output shape (no output schema, but list tools typically return arrays) or pagination 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%, so the schema fully documents both parameters including the nested workspace object. The description's note about workspace being per-call targeting without changing defaults adds slightly beyond the schema but is largely redundant. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'List exact app component documentation categories from the hosted builder.' This is distinguishable from siblings like whodb_platform_app_component (singular) and whodb_platform_app_components. However, it doesn't explicitly contrast with those siblings, keeping it from 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?

Provides one conditional guideline: 'Call before using unfamiliar component types.' This implies usage context but gives no explicit when-not-to-use, no mention of singular sibling tool whodb_platform_app_component as an alternative, and no prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: results are paginated one page per request, and the workspace argument applies per-call "without changing defaults" (i.e. non-mutating session state).

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 purpose followed by the pagination and workspace caveats. No filler sentences, though the workspace sentence is slightly tangential to the core listing behavior.

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 listing tool with no output schema, the description supplies the useful essentials: what gets returned (app.json, shared files, pages) and how results are chunked. It stops short of describing ordering or how to know the full page set is exhausted, but nothing critical for a correct call 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%, so every parameter (id, env, fields, version, workspace.*) is already documented, establishing the baseline of 3. The description adds only a light nuance about workspace being per-call and non-persistent, which the schema largely already conveys.

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 ("List") and resource ("draft files of one hosted app") and enumerates the contents: app.json, shared files, and every page. This distinguishes it from generic file listing tools, but it never names the closest sibling, whodb_platform_app_page_files, or contrasts with app_version_view, leaving the agent to infer the boundary.

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

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

The phrase "read one page per request so large apps fit" implies a paginated usage pattern for large apps, which is useful context. However there is no explicit when-to-use/when-not guidance and no named alternative for the related but distinct app_page_files or version-view 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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds that this operates on a 'hosted draft' via an 'in-app builder audit', which usefully implies a non-mutating inspection of draft content. It adds no depth on cost, latency, or limits, so a 3 is right given annotation coverage.

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 capability and followed by the workspace note. The enumerated output areas are dense but earn their place as scope definition. Minor redundancy with the schema's workspace wording keeps it from a 5.

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

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

With no output schema, the description usefully enumerates what the map surfaces (events, scripts, bindings, state, navigation, overlays, function contract issues), giving the agent a sense of the return scope. Combined with annotations covering read-only safety and schema covering all params, the definition is adequately complete, though selection guidance versus siblings is absent.

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 id, page, and workspace are fully documented in the schema, including that workspace is per-call only. The description repeats the workspace targeting idea ('for per-call targeting without changing defaults'), which the schema already states. No syntax or format detail is added, 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 ('Map') and a concrete resource set (a hosted draft's page events, scripts, bindings, state, navigation, overlays, and function contract issues) via the in-app builder audit. This is far more specific than a tautology, and the niche 'logic graph' concept is legible from the enumerated dimensions. It does not differentiate from the many neighboring app/graph tools (app_view, resource_graph), keeping it out of 5 territory.

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 named alternative among the dense sibling set (e.g. whodb_platform_app_view, whodb_platform_workspace_map, whodb_platform_resource_graph). The only usage-adjacent sentence concerns workspace targeting, not tool selection. An agent must infer context from the description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so safety is covered. The description adds one useful behavioral note — workspace targeting is per-call and does not change session defaults — but says nothing about the volume, format, or content of the returned files.

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 purpose and followed by the workspace behavior. No filler or 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?

There is no output schema, so the description should ideally describe what 'generated files' actually returns (paths? contents? a manifest?), but it leaves that to inference. It is adequate for a read tool whose annotations cover safety, but not fully complete for the 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 coverage is 100%, so the schema documents all five parameters including the nested workspace object. The description adds a semantic nuance ('without changing defaults') about how the workspace param behaves, but this is a baseline addition on top of already-complete schema docs.

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

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

States a clear verb+resource: 'Read the generated files for one page of a hosted app.' The 'for one page' scoping differentiates it from the broader whodb_platform_app_files sibling, though it doesn't name that sibling explicitly. An agent can distinguish the granularity without opening either schema.

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

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

No when-to-use guidance or conditions for choosing this over whodb_platform_app_files, whodb_platform_app_views, or the various app view tools. The only routing hint ('Page name from whodb_platform_app_views') lives in the parameter 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so safety and repeatability are covered. The description adds useful scope context by noting per-call workspace targeting without changing defaults, but it does not discuss pagination behavior or result characteristics beyond what the schema implies.

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

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

Two compact sentences, front-loaded with the core action and followed by the key targeting caveat. There is no wasted text.

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

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

For a read-only list tool with fully described parameters and no output schema, the description provides enough context to call it correctly, including the project scope and per-call workspace behavior. It could still mention pagination/filtering behavior or return-shape expectations more explicitly.

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 parameters, including nested workspace fields, are already documented in the schema. The description briefly mentions the workspace shape and per-call behavior, but adds little semantics beyond the structured parameter descriptions, so baseline 3 applies.

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

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

The description states a specific verb and resource ("List hosted ontology-powered apps") and scopes it to the selected project. It is clear enough to distinguish this as a list operation, but it does not explicitly differentiate from nearby app-related siblings such as whodb_platform_app or whodb_platform_app_views.

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 explains that workspace targeting is per-call and does not change defaults, but it gives no guidance on when to use this tool versus alternatives. There are no exclusions or decision rules for choosing between this and sibling app-listing/view 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 readOnly/idempotent/openWorld, and the description adds real behavioral context: it discloses the returned artifacts (WebP, text, diagnostics, optional trace), the runtime compatibility caveat for traces, and that hosted writes are blocked. It stops short of explaining failure modes or pagination/diagnostics semantics, so not a full 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?

Front-loaded with the core purpose, then returns and targeting constraints in compact sentences. Dense but each clause carries information; only slight redundancy with the annotation title text.

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

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

With 13 params, nested workspace, an output schema, and full annotations, the description covers the essentials an agent needs (device presets, actions/script, targeting, blocked writes). Missing only explicit guidance on when a trace is available or how diagnostics should be interpreted.

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 both the flat fields and the nested workspace object are already documented. The description reiterates workspace targeting and defaults but adds little syntactic detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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 (capture) plus resource (rendered app page) and the distinguishing capabilities (device sizes, post-actions/JS, returned artifacts). An agent can tell this apart from read-only siblings like whodb_platform_app_views or whodb_platform_app_view, which merely list or fetch views.

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 context (rendering a page with optional actions before capture) and the workspace field points to discovery tools, but it never explicitly says when to use this versus app_view/app_views, nor any prerequisite or exclusion conditions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, covering the safety profile, and the title duplicates the description verbatim. The description's one addition — that workspace targeting applies 'without changing defaults' — is genuinely useful session-state context, but it is also stated in the schema for the workspace object, so it adds little beyond what structured data already provides. No behavior around missing categories, auth requirements, or result shape is disclosed.

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 tight sentences with zero filler; the core purpose is front-loaded and the secondary workspace-targeting note follows. The inline {host, org, project} shorthand is compact rather than redundant.

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-only lookup with no output schema, the description covers the workflow origin of the input and how to target a workspace without side effects, which is close to enough. It stops short of describing what the returned 'usage' contains or what happens when the category name doesn't resolve, which is the only meaningful 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 nested workspace object documents host/org/project plus the resolution order (session default set by whodb_platform_session_use, then saved defaults), so the schema carries the burden. The description's restatement of the workspace shape and 'without changing defaults' is a useful summary but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('look up') and resource ('app SDK usage') scoped to a single category, and explicitly ties itself to the sibling 'whodb_platform_app_sdks' as the source of valid categories, which cleanly separates the singular detail tool from the plural list tool. Slight deduction because 'SDK usage' is ambiguous — it could mean usage documentation, usage examples, or usage statistics — so the agent still doesn't know exactly what payload to expect.

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 establishes a clear two-step workflow: enumerate categories with whodb_platform_app_sdks, then look up exact usage for one of them here. It gives no explicit when-not-to-use or named alternative beyond the list tool, but for a narrow detail-lookup tool the context is sufficient to route correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint. The description adds genuinely new behavior beyond those: the data comes from a "hosted builder" and workspace targeting is per-call only, "without changing defaults" — a useful scoping detail an agent would otherwise have to guess.

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

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

Three short sentences, front-loaded with the purpose, followed by the when-to-use and the scoping note. No filler, though the workspace targeting sentence could be slightly tighter.

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?

A read-only list tool with annotations covering safety and no output schema to explain, so the description carries sufficient weight. It could say more about result content or what happens when the optional `name` filter is absent, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates the workspace shape without adding new semantics (e.g. what a valid SDK category name looks like, or behavior when `name` is omitted despite it not being schema-required). 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: "List exact app SDK documentation categories from the hosted builder." Clear what it returns, though it never explicitly distinguishes itself from the singular sibling whodb_platform_app_sdk, leaving the list-vs-lookup distinction to inference.

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

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

"Call before writing data or function integration code" gives a clear trigger condition, which is more than most list tools offer. It stops short of naming the alternative tool (app_sdk) or saying when NOT to call it, so it isn't full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the per-call targeting nuance: workspace does not change session defaults. Useful, but no info on pagination, return shape, or what 'promoted' vs draft 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?

Two tight sentences, front-loaded with the action and scoping constraint. No waste, though very short for a five-parameter, nested-object 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?

Given 5 params, nested workspace object, and no output schema, the description is thin. It resolves the workspace targeting question but leaves the core 'which version/id/env combination' and sibling differentiation to the schema, which is adequate but not strong.

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 3 applies. The description confirms the workspace object is per-call only and that it overrides session defaults set by whodb_platform_session_use, which is additive context, but it does not explain id vs version vs env semantics 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?

States a specific verb+resource: reading a promoted hosted app version. Clear enough on its own, but 'promoted' and its distinction from siblings like whodb_platform_app_views, whodb_platform_app_view, and whodb_platform_active_version is not explained, so an agent must guess which app-view variant to pick.

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, when-not-to-use, or alternative naming. The crowded sibling set (app_view, app_views, app_files, app_components, object_versions, active_version) means an agent gets no routing signal. The only guidance is implicit in the workspace text about defaults.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, and the description adds nothing beyond them: its first sentence is a verbatim restatement of the annotation title, and its second repeats the workspace semantics already in the schema. No mention of result shape, pagination, or what "generated files" means in practice.

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, no filler words, and the read scope is front-loaded before the targeting note. It is efficient, though the second sentence is low-value duplication rather than earned 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?

No output schema exists and no annotations explain return behavior, so the description must clarify what a "view" yields (rendered output, metadata, file list?) and how id/env/version select among them. Given the dense app_* sibling cluster and a nested workspace object, the definition leaves the agent guessing.

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% across all five parameters (id, env, fields, version, workspace and its nested host/org/project), so the schema carries the full burden. The description's only parameter sentence restates the workspace object, adding no syntax or precedence detail beyond what the schema already documents, so baseline 3 applies.

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

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

The description gives a verb ("Read") and an object ("current hosted app view and generated files"), so it is not a tautology. However, "view" is left undefined even though the sibling list contains whodb_platform_app, whodb_platform_app_views, whodb_platform_app_version_view, whodb_platform_app_files and whodb_platform_app_screenshot; an agent cannot tell which of these returns what.

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 statement of when to call this tool versus the many app-related siblings, nor any precondition such as needing an app id or a session host. The only guidance present (per-call workspace targeting) duplicates the input schema rather than adding selection logic.

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

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

Annotations already declare readOnly, idempotent, and openWorld behavior. The description adds that workspace targeting is per-call and does not change defaults, which is useful, but it does not explain the many capture/interaction parameters visible in the schema.

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 concise sentences with no filler. The core listing purpose is front-loaded, followed by the next-step tool reference and the workspace targeting 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?

The output schema, annotations, and full schema descriptions cover much of the burden. However, the description is very short relative to a 13-parameter schema that includes action, script, trace, viewport, and device-emulation options, leaving some ambiguity about whether this tool only lists pages or also captures/interacts with app views.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description only restates the app identifier and workspace object concepts, adding little beyond what the schema provides.

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: list pages in a hosted app by ID or exact name. It distinguishes itself from whodb_platform_app_screenshot by directing the agent to pass a returned page there, though it does not explicitly differentiate itself from the singular whodb_platform_app_view or whodb_platform_apps.

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 next-step context: use a returned page with whodb_platform_app_screenshot. It also explains per-call workspace targeting without changing defaults. It stops short of explicit when-not-to-use guidance or naming all relevant alternatives.

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

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

Annotations already carry readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is largely covered. The description adds genuinely new behavioral context by stating it 'never creates confirmation tokens,' which tells the agent this planning tool will not hand off to the confirm/pending flow that other mutating siblings use.

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

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

Four sentences, front-loaded with the primary purpose before the usage trigger and behavioral notes. Minimal waste, though 'It is read-only' partially duplicates the readOnlyHint annotation.

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 planning tool with no output schema, the description is nearly complete: it explains scope, when to call it, its safety profile, and the phases planned. It could say more about the shape of the returned plan, but the enumerated phases largely cover what an agent needs.

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

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

Schema description coverage is 100%, so the schema already documents goal, fields, workspace, omit_files and omit_lineage. The description only restates the workspace targeting behavior ('for per-call targeting without changing defaults') that the schema already explains, and adds nothing about the fields/omit_* parameters; 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: 'Return an end-to-end hosted platform build plan for a user goal,' and enumerates the phases (scope, ingest, persist, model, automate, runtime support, governance) it covers. It reads as clearly distinct from a bundle-import or workflow plan, though it never explicitly contrasts itself against the plan-like siblings such as whodb_platform_write_plan or whodb_platform_workflow_plan.

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

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

'Use this before coordinating a cross-resource workflow' gives a concrete when-to-use trigger. No exclusions or named alternatives are provided, so the agent must infer the boundary against the other planning tools, but the positioning statement is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds useful behavior beyond those annotations: it returns create/skip actions and per-call workspace targeting does not change defaults.

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 definition is three short sentences with the main comparison purpose front-loaded, followed by the input source and workspace targeting behavior. Every sentence adds useful information.

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

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

With a full schema, output schema, and rich annotations, the description provides enough context for correct invocation. It covers the input source, read-only diff behavior, return action shape, and workspace scoping without duplicating schema details.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by naming bundle_json as coming from bundle_export or the CLI resources export command and by clarifying that workspace targeting is per-call without changing defaults.

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: "Compare a project bundle against the selected hosted project." It also clarifies the read-only diff behavior by stating that it returns create/skip actions, which distinguishes it from mutation-oriented siblings such as bundle import or workflow apply.

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 explains where the bundle_json input comes from (bundle_export or CLI resources export) and clarifies that the workspace object targets a project for that call only. It does not explicitly name the import/apply alternative or state when not to use diff, so it stops short of full 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?

Annotations already cover readOnly/idempotent/openWorld, and the description adds real behavioral context beyond them: secret values are never exported, file content is only included when include_files is true, and it is capped by max_file_bytes. It does not describe output shape or size, but the presence of an output schema reduces that burden.

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

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

Four short sentences with the purpose front-loaded and no filler. The final sentences largely restate schema parameter descriptions, which is slight redundancy but not wasteful.

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 export tool with an output schema and full annotation coverage, the description supplies what is needed: what gets exported, what never gets exported, when file content is included, and how targeting works. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the nested workspace object is fully documented in the schema, including the resolution order of session default then process/saved defaults. The description restates the include_files/max_file_bytes gating rather than adding syntax or format details, so baseline 3 applies.

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

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

The description uses a specific verb and resource: "Export selected hosted project metadata as a portable bundle," and enumerates the resource classes included (secrets, datasets, ontologies, transforms, functions, folders, files). It does not explicitly point to siblings like whodb_platform_bundle_import or whodb_platform_bundle_diff, so differentiation relies on the tool name.

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

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

The description says the workspace arg allows per-call targeting without changing defaults, which implies usage, but it never states when an agent should choose this over bundle_diff, bundle_import, or clone. There is no explicit when/when-not guidance or prerequisites.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the bar is lower. The description still adds non-obvious behavior: default mode is a preview that returns a confirmation token, and confirm must wait for user approval. It does not describe what happens on conflict by default or the failure mode when rename_conflicts and overwrite_conflicts are both set, 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?

Four short sentences, front-loaded with purpose then the plan/confirm workflow, then the option list and workspace targeting. Nothing is wasted, though the parameter enumeration in sentence four is largely redundant with the schema.

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

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

For a destructive, multi-option, nested-workspace mutation with an output schema and rich annotations, the description covers the critical workflow: preview default, confirmation token, user approval gate, and target resolution. The only omission is conflict-resolution precedence, which the agent must infer from 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 100%, so all five parameters, including the nested workspace fields, are already documented in structured data. The description only restates them ("Supports prefix, rename_conflicts, and overwrite_conflicts", workspace targeting "without changing defaults") without adding format, mutual-exclusivity, or interaction semantics.

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 ("Import a project bundle into the selected hosted project") and implicitly distinguishes itself from the sibling read-only operations whodb_platform_bundle_export and whodb_platform_bundle_diff. An agent can tell it apart from whodb_platform_bundle_import_plan, which it explicitly names as a predecessor.

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

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

Gives explicit sequencing rules: "Use whodb_platform_bundle_import_plan first when possible" and "do not call whodb_platform_confirm until the user approves the import preview." It names the alternatives (plan, confirm) and the condition that gates each, leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered; the description still adds real value by stating the tool never mutates and by telling the agent how execution is actually performed. It does not describe what the plan output contains, but an output schema exists to carry that.

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

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

Three tight sentences: purpose first, then the plan-only constraint, then the execution path and targeting note. No filler, and the most decision-relevant fact (plan-only) 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?

An output schema exists so return format need not be explained, and the description covers the plan/execute split and per-call workspace targeting. The only gap is that it doesn't distinguish itself from the sibling bundle_import tool an agent will also see in the list.

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

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

Schema description coverage is 100%, so the schema already documents bundle_json, prefix, rename_conflicts, overwrite_conflicts, and the nested workspace object. The description only restates the workspace targeting behavior already captured in the schema, adding no syntax or precedence detail beyond 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?

States a specific verb and resource ('Plan how a project bundle would import') plus the explicit scope limitation ('intentionally plan-only'), which clearly separates it from an executing import. It does not name the sibling whodb_platform_bundle_import, even though that tool's presence makes the distinction worth spelling out.

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

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

Gives a concrete when-to-use (plan, review) and a when-not/alternative (execution happens via the CLI 'resources import --yes' command). The routing is clear, but it points to a CLI command rather than clarifying the relationship to the very similar MCP sibling, leaving some ambiguity an agent may stumble on.

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 and idempotentHint; the description adds that it "does not execute any change" and describes its output shape ("directly connected resources and recommended reads") plus that workspace targeting is per-call and does not change defaults. That is genuine context beyond the annotation set.

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

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

Three tight sentences, front-loaded with the purpose, then how to call it, then usage/return behavior. No filler, though the workspace sentence is slightly dense with brace notation.

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 carries the burden and does state what is returned and that no change is executed. It covers usage timing and targeting adequately; minor gaps remain around pagination or result limits, but nothing critical for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters, including action examples and the workspace object. The description reinforces the core resource/id/action triple and the workspace non-persistence behavior but adds little that the schema lacks, matching the baseline 3.

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

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

States a specific verb+resource ("Analyze direct graph impact") and scopes it to "directly connected resources." An agent can tell it is an impact-analysis read, but it does not explicitly differentiate itself from adjacent siblings like whodb_platform_deletion_impact or whodb_platform_ontology_reference_impact.

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 timing guidance: "pass resource, id, and optional action before update, delete, deploy, run, move, or promotion work." This tells the agent when to reach for it, but names no alternative tools or exclusion conditions.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds the crucial two-step preview/confirm gating, which materially changes how an agent should behave. It also clarifies that the workspace parameter is scoped to a single call. It does not say what the clone copies (permissions, versions, dependents) or how name collisions are handled.

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: the capability and scope come first, then the confirm-gating rule and the workspace-targeting caveat. Every clause conveys actionable information.

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

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

For a destructive, non-idempotent mutation with a nested workspace object, the description covers the safety workflow and per-call targeting, and an output schema exists so return values need no explanation. What remains unstated is which artifacts come along with a clone and any preconditions on the source resource.

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 resource, source, new_name and the nested workspace object are all documented in the schema itself. The description's note that workspace accepts {host, org, project} without altering defaults largely restates the schema's 'Optional target for this call only' wording, so it adds only marginal value. Baseline 3 applies when the schema carries the semantics.

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 (clone) and enumerates the exact resource types it operates on (dataset, ontology, transform, function) within the selected project. This implicitly separates it from the create/update/delete siblings, though it never names an alternative such as whodb_platform_create_dataset or whodb_platform_create to draw the 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?

Gives concrete workflow guidance: the default call returns a confirmation token and whodb_platform_confirm must not be invoked until the user approves the preview. It also explains that workspace targeting is per-call and does not change defaults. No guidance is offered on when to clone versus create a fresh resource, which would complete the picture.

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 non-readonly, destructive, non-idempotent, open-world behavior, and the description goes further by disclosing token expiry, the fact that the token is not proof of human approval, and that uploads read the file at execution time rather than from a snapshot — a real TOCTOU caveat that changes how an agent should behave.

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

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

Front-loaded with the core action, then preconditions, then caveats — a sensible order with no filler. Some sentences carry multiple clauses (approval caveat plus upload caveat), which makes it dense but not wasteful.

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 an output schema exists, the description need not explain return values, and it covers what is left: sequencing after a write preview, token lifetime, approval semantics, and per-call workspace targeting with a pointer to host/org/project discovery tools. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so the heavy lifting is done structurally. The description still adds meaning beyond the schema: it clarifies where the token comes from and that it is time-limited, and confirms the workspace block is per-call targeting that does not change session defaults.

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: 'Confirm and execute a pending hosted WhoDB platform write.' This clearly distinguishes it from whodb_platform_pending (which lists pending writes) and whodb_platform_write_plan (which plans them), so an agent can pick the right tool without inspecting schemas.

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

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

Explicitly names the trigger ('Use the confirmation_token returned by hosted platform write tools'), the precondition ('Only call this after the user has approved the pending write preview'), and a hard timing constraint ('Tokens expire after 5 minutes'). The when-to-call and the sequencing relative to write tools are fully specified.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false. The description adds real value beyond those: the default confirmation-token preview flow, the requirement to obtain user approval before confirming, that permission checks are enforced server-side, and that projectId/id are injected. It doesn't explain what the create actually returns post-confirmation, but it is well above the annotation baseline.

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

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

Front-loaded with the core action, followed by the resource list and then operational constraints. It is dense but each sentence carries information; the resource enumeration is long but genuinely useful. No filler.

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

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

For a mutation tool with no output schema, the description covers the critical preview/confirm lifecycle, permission enforcement, and default-workspace injection. It leaves desired but non-critical gaps (error behavior on resource-type mismatch, what the confirmed call returns), yet nothing essential for a correct invocation 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%, so the schema already documents id, action, payload, resource, workspace, payload_json, and idempotency_key. The description adds only the auto-injection note, and it emphasizes the legacy payload_json field ("Pass payload_json as a JSON object") even though the schema says to prefer payload, which is mildly confusing rather than additive.

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

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

States a specific verb+resource ("Create a hosted platform resource") and enumerates the supported resource types, which is genuinely informative. It doesn't differentiate itself from dedicated siblings like whodb_platform_create_dataset, whodb_platform_create_ontology_fast_lookup, or whodb_platform_source_create, which overlap logically, so an agent can't tell from the text alone which to pick.

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 the preview/confirm workflow ("do not call whodb_platform_confirm until the user approves") and notes that projectId is auto-injected, which is contextual usage help. However it never states when to use this generic create over the specialized create_* siblings, so the primary routing decision is left to inference.

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

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

Annotations declare the tool is destructive and non-idempotent, but the description adds the critical non-obvious behavior: the default mode returns a confirmation token and a preview must be user-approved before calling whodb_platform_confirm. It also discloses that workspace targeting is per-call only and does not change defaults, which annotations cannot convey.

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

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

Four tightly-written sentences, front-loaded with the purpose, then the sibling routing, then the confirm-token safety note, then the workspace semantics. No filler and every sentence carries actionable information.

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

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

For a destructive creation tool with 7 params, no output schema and nested workspace, the description covers purpose, alternative routing, the confirm-preview safety workflow, and per-call workspace scoping. Everything an agent needs to invoke it correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema documents name, columns, source_id, workspace, schema_mode, etc. The description adds a useful cross-parameter interaction that the schema does not: workspace is 'for per-call targeting without changing defaults', clarifying scope semantics beyond the per-field 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 opens with a specific verb+resource: 'Create a hosted dataset through the selected project', clearly distinguishing it from siblings like whodb_platform_datasets (list) or whodb_platform_dataset (fetch). It also explicitly positions the tool against the raw whodb_platform_create sibling.

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

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

It says when to use this over the generic whodb_platform_create ('Use this typed wrapper for normal dataset creation instead of raw whodb_platform_create when possible'), and gives an explicit workflow exclusion: don't call whodb_platform_confirm until the user approves the preview. This is exactly the routing guidance an agent needs.

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 destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds important workflow context: a confirmation token is returned and the confirm tool should only be called after user approval. This is valuable beyond annotations, though it doesn't detail what gets destroyed or rate 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?

The description is concise with three sentences, front-loading the main action. It is efficient, though the phrase 'for one hosted ontology' could be tightened.

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 mutation nature, no output schema, and full schema descriptions, the description provides necessary workflow context about confirmation. It is nearly complete, missing only explicit permission requirements or side effects of creating a fast lookup.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description mentions 'Pass ontology property names in fields' and explains workspace targeting, but it does not add syntax or format details beyond what the schema provides. 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 states a specific verb and resource: 'Create a fast lookup for one hosted ontology.' It is clear what the tool does, though it does not differentiate from sibling tools like create_ontology_fast_lookup vs other lookup-related tools beyond the 'fast' qualifier.

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

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

It gives clear usage context: default mode returns a confirmation token, do not call confirm until user approves preview. It also explains workspace targeting. However, it does not explicitly state when to use this vs alternatives like delete_ontology_fast_lookup or other creation 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, idempotentHint and openWorldHint, so the description is not responsible for the safety profile. It still adds real behavior: the enumerated return payload and the fact that per-call workspace targeting does not mutate session defaults. It omits any note on result size, cost, or truncation for what is an aggregate over multiple resource classes.

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

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

Four short sentences ordered purpose → when to use → what you get → parameter note; nothing is buried. The final workspace sentence is largely redundant with the schema and could be dropped without loss.

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

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

For a zero-required-param aggregate read with no output schema, the agent learns the content categories, the intended position in a workflow, and the targeting behavior. Because there is no output schema, the description is the only guide to structure, and it names sections but not their shape or how 'fields' filters them.

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 (fields, workspace.*, omit_files, omit_lineage) are already documented, which sets the baseline at 3. The description restates the workspace {host, org, project} targeting semantics that the schema already explains, adding the 'without changing defaults' nuance but nothing about how 'fields' interacts with the returned sections.

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 pairs a specific verb ('Summarize') with a scoped resource ('selected-project data-model resources') and enumerates exactly what the summary contains (sources, datasets, ontologies, graph relationships, modeling gaps). It is distinguishable from near-neighbors like workspace_summary or project_health by the data-model framing, though it never names a sibling 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?

'Use this before ontology, dataset, or lineage work' gives a concrete trigger and implicitly routes the agent toward the three tool families it precedes, and the promise of 'read tools an agent should call next' frames it as a starting point. There is no explicit when-not condition, but the positioning 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 already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds that the workspace argument enables per-call targeting without changing defaults, which is useful behavioral context, but it does not describe return behavior, error cases, or 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?

Two sentences, front-loaded with purpose then targeting behavior. There is no filler, and each sentence contributes a distinct piece of information.

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

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

For a simple read-only inspection tool with rich annotations and full schema coverage, the description gives enough to invoke it correctly. The main remaining gap is that it does not clarify what 'inspect' returns, though the fields parameter and annotations make the output shape reasonably inferable.

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

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

Schema description coverage is 100%, so the schema already documents id, fields, and workspace subfields. The description only repeats that the tool accepts an id and a workspace object; it adds no format, constraint, or selection detail 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 states a specific verb and resource: 'Inspect one hosted dataset by id.' The singular 'one hosted dataset' distinguishes it from list-oriented siblings like whodb_platform_datasets, but it does not explicitly name alternatives or contrast with whodb_platform_dataset_rows.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives. The description implies use when you have a dataset id, but it does not say when to prefer this tool over whodb_platform_datasets or whodb_platform_dataset_rows.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are capped by both the requested limit and the MCP --max-rows setting, and per-call workspace targeting does not change session defaults. That is real added context beyond the annotations.

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

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

Two sentences with no filler; the purpose is front-loaded and the second sentence carries the two operational facts. Tight and appropriately sized for a simple read 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 read-only preview tool with full schema coverage and no output schema, the definition covers purpose, result capping and targeting scope. It does not describe the row shape returned, but 'preview rows' plus the 100% schema coverage makes that a minor 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%, so the baseline is 3. The description goes slightly beyond the schema by explaining the cap interaction between limit and --max-rows and clarifying that workspace is a one-call override that leaves defaults intact, which the schema's wording 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?

States a specific verb+resource: 'Preview rows for one hosted dataset.' An agent knows exactly what it does. However, it never differentiates itself from close siblings like whodb_platform_source_rows or whodb_platform_ontology_rows, which are the likely confusions for a rows-preview tool.

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

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

The workspace sentence gives implied usage (omit to use session default, pass per-call to target a specific host/org/project). But there is no when-to-use vs alternative guidance, and no mention of when to prefer this over the source_rows or ontology_rows siblings. Usage is inferred, not directed.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful non-annotation context: that the workspace argument targets a single call 'without changing defaults', which clarifies session-state behavior an agent cannot read off the annotations.

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

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

Three short sentences, front-loaded with the core action, then filters, then the targeting mechanism. No filler and nothing buried.

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

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

For a read-only list tool with no output schema, the description names the resource, the scoping, the useful filters, and the override mechanism, while annotations carry the safety profile and the schema carries every parameter. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema itself documents all ten parameters including the nested workspace object. The description only echoes the name/schema_mode filters and the workspace shape, adding no syntax, default, or pagination nuance beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('List') and resource ('datasets') scoped to the 'selected hosted project', which an agent can parse immediately. However, it does not distinguish this list tool from the singular sibling whodb_platform_dataset or from whodb_platform_dataset_rows, so an agent must infer the difference from the name alone.

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

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

'Use name and schema_mode filters when known' gives a light hint about when filters are worth attaching, and the workspace sentence explains per-call targeting. But there is no when-not guidance, no mention of alternatives like the singular dataset tool, and no statement of prerequisites (e.g. a selected project must exist).

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 destructiveHint=true and idempotentHint=false, but the description adds substantial behavioral context beyond them: the default mode returns a confirmation token and requires explicit user approval, permission checks are enforced server-side, and workspace targeting is per-call without changing defaults. This is exactly the destructive-operation context an agent needs and cannot get from structured fields alone.

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

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

Front-loaded with the action and resource list, then the destructive warning, then the confirmation protocol. Dense but mostly earned; the resource enumeration is long yet operationally necessary since the enum is not expressed in the schema.

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

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

For a destructive 7-parameter mutation with no output schema, the description covers the confirm workflow, resource-specific payload routing, permissions, and targeting. It omits whether deletion is soft/recoverable (relevant given the whodb_platform_restore and whodb_platform_deleted_resources siblings) and what the confirmation token looks like.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds cross-parameter semantics the schema does not encode: when to use id versus payload_json, and the specific sourceId/ref/values shape required for source_object. The workspace targeting behavior is also clarified relative to session defaults.

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

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

States a specific verb+resource ('Delete a hosted platform resource') and enumerates the supported resource types, which is far more than a tautology. It does not, however, differentiate itself from overlapping siblings like whodb_platform_source_delete, whodb_platform_delete_ontology_fast_lookup, or whodb_platform_project_delete, so an agent must infer which delete entry point applies.

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 operative guidance: pass id for normal resources, use payload_json with sourceId/ref/values for source_object, and follow the default preview-then-confirm flow before calling whodb_platform_confirm. It stops short of naming the alternative delete tools or stating exclusions, so it lacks the explicit when-not routing of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered. The description adds the visibility scope ('visible to the signed-in user') and the per-call workspace targeting behavior, but omits anything about pagination, ordering, or what 'restorable' concretely means (retention window, etc.).

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 tight sentences with the core purpose front-loaded and the targeting caveat second. No filler, though it is terse enough to leave gaps.

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

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

For a read-only list tool with no output schema and full schema coverage, the description covers purpose and targeting adequately. It does not describe the returned shape or filtering behavior, but those are minor for this tool class.

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

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

Schema coverage is 100%, so the schema documents all five parameters. The description slightly reinforces the workspace targeting semantics, but largely repeats what the schema already spells out, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List ... resources') scoped by 'restorable' and 'visible to the signed-in user', which clearly frames it as the listing counterpart to the deletion/restore tools. It does not explicitly name a sibling (e.g. whodb_platform_restore) to route the agent, 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 word 'restorable' implies this is the discovery step before whodb_platform_restore, but no explicit when-to-use, when-not, or alternative is stated. Usage must be inferred.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds non-annotation context: the default mode only previews and returns a confirmation token, and that workspace targeting does not mutate session defaults. It still doesn't say what collateral effects the deletion has or whether it is reversible.

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 tight sentences, purpose front-loaded, no filler. There is minor overlap with the schema's own workspace description, but nothing wasteful.

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 carry the flow, and it does enough: it explains that the default call yields a token rather than performing the delete and that workspace selection is per-call. It omits what a confirmed deletion actually removes and whether recovery is possible, which matters for a destructive tool.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and the nested workspace object. The description restates workspace targeting ('per-call targeting without changing defaults') with no added syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('Delete one hosted ontology fast lookup by id'), which cleanly separates it from the sibling create/lookup tools. An agent can identify the target and the operation 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?

Explains the two-step confirm workflow ('default mode returns a confirmation token; do not call whodb_platform_confirm until the user approves'), which is real procedural guidance for this specific tool. It stops short of saying when an agent should not delete or what alternatives exist (e.g. archive/restore), so it falls below a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. On top of that the description discloses the two-step preview/confirm workflow and that workspace targeting is per-call and does not change defaults – behavior an agent could not infer from the annotations alone.

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

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

Four short sentences with the action front-loaded, followed by the parameter hint and the workflow warning in priority order. No padding, though it could be marginally tighter by merging the values hint into the same sentence as the delete action.

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

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

For a destructive single-row delete with full annotation coverage and a complete schema, the description supplies the key missing piece – the preview-then-confirm safety flow. No output schema exists, but the confirmation-token return behavior is stated, so an agent has enough to act correctly.

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

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

Schema description coverage is 100%, so the schema already documents values, entity_id, and workspace. The description adds only a light hint that values identify the row and are usually the primary key property, which is marginally beyond the schema and sets the baseline of 3.

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

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

States a specific verb and resource ("Delete one hosted ontology row") that an agent can distinguish from the add/update siblings. However, it does not name the closer alternatives like whodb_platform_delete_ontology_fast_lookup or whodb_platform_delete, so the differentiation from siblings relies on their names rather than explicit routing.

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 concrete operational guidance: pass row-identifying values (usually the primary key), the default mode returns a confirmation token, and the agent should not call whodb_platform_confirm until the user approves the preview. It stops short of stating when to prefer this over the fast_lookup or generic delete siblings, so no explicit exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the non-mutating nature is covered structurally. The description adds real value in noting the workspace block is per-call targeting that leaves defaults unchanged, but it does not say what the inspection actually surfaces (dependents lists, blocking conditions, scoping of results).

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

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

Two sentences, zero filler, with the purpose stated first and the parameter nuance second. Nothing needs trimming and nothing is buried.

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 inspection tool with full annotation coverage, no output schema, and fully documented parameters, the description is nearly sufficient — it conveys the intent and the targeting model. The gap is that with no output schema present, the description could briefly characterize what the inspection returns (e.g. blocking dependents vs. advisory references) to help the agent interpret results.

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 100% schema description coverage, the schema already documents all five parameters including the nested workspace object's host/org/project semantics and the session-default cascade. The description's contribution is limited to reinforcing that workspace targeting is scoped to a single call, which the schema already states for the host field — a baseline 3.

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

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

States a specific verb ('Inspect') and a specific resource set ('hosted dependents, references, and shared resources'), plus the temporal context ('before deletion'). It is distinguishable from neighbors like whodb_platform_delete or whodb_platform_restore, though it never names the adjacent read-only impact siblings (change_impact, ontology_reference_impact, share_dependents) that an agent might confuse it with.

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 'before deletion' implies the usage context — a pre-flight check prior to a destructive call — which is genuinely useful guidance. But it gives no explicit when-not, no prerequisites, and no pointer to the alternative impact/reference tools, so the agent must infer 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?

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so safety and repeatability are covered. The description adds one genuinely useful behavioral detail — that workspace targets a single call without changing the session default — but says nothing about result volume, pagination, or whether sharing visibility is permission-filtered.

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 tight sentences with the purpose front-loaded and no filler. The second sentence is largely redundant with the workspace schema description, which keeps it short of a 5.

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

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

For a 10-parameter, zero-required, read-only list tool with no output schema and full schema coverage, the description covers the core purpose but omits return shape and pagination expectations (limit/offset exist in the schema but no guidance on using them). Adequate, not complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of workspace {host, org, project} for per-call targeting restates what the workspace schema description already says, adding no syntax or precedence detail beyond 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?

States a specific verb and resource ('List ontologies other projects share that the selected project may reference'), which is clear. However, it does not distinguish itself from the very close sibling whodb_platform_shared_ontologies (and shared_by_me/shared_with_me), so an agent cannot tell from the description alone which of these list tools is the right one.

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 statement, no exclusions, and no named alternatives despite several near-identical siblings (shared_ontologies, ontologies, shared_by_me, shared_with_me). The only contextual hint is that workspace can target a project per call, which is task mechanics rather than selection guidance.

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

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

Annotations already cover read-only/idempotent/open-world, so the description focuses on the useful extra: it names the categories it inspects (login, selected workspace, manifest availability, actionable warnings) and clarifies the non-destructive nature of per-call targeting ('without changing defaults'). Output schema exists, so return-value detail is not required.

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

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

Four short sentences, front-loaded with purpose then usage then behavior then parameter note. No filler; a slightly tighter single paragraph would earn a 5.

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

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

Given a single optional parameter, full schema coverage, annotations, and an output schema, the description supplies what is needed: what it inspects, when to call it, and that targeting is per-call only. Missing only a pointer to the nearest alternative diagnostics 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 workspace description already explains the session-default fallback and points to discovery tools. The description's 'per-call targeting without changing defaults' largely restates that, adding little 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?

States a specific verb and resource – a readiness/diagnostic check on hosted WhoDB MCP – and enumerates what it reports (login, workspace, manifest, warnings). It is distinguishable from generic siblings like whodb_platform_status or whodb_platform_setup_status only by the word 'MCP', not by any explicit contrast.

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

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

'Use this when platform tools fail or before a workflow' gives clear triggering conditions. It does not say when *not* to use it, nor how it differs from the many adjacent health/status tools (setup_status, runtime_readiness, project_health).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds a genuinely new behavioral caveat — suggested mappings are advisory and the platform still validates writes — plus that workspace targeting does not mutate session defaults. Return-shape and pagination behavior remain unstated, but the added caveats exceed annotation coverage.

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

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

Purpose is front-loaded in the first sentence and the remaining sentences each carry distinct value (workflow routing, field preference, write-validation caveat, workspace scoping). It is dense but not padded; the density is appropriate for a five-parameter tool.

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

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

With read-only annotations carrying the safety profile, full schema coverage on all five parameters, and no output schema to explain, the description covers the remaining needs: what it does, how it fits before promotion, how to choose fields, and that mappings are non-authoritative. Nothing essential for correct invocation 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%, so the baseline is 3. The description goes beyond it by prescribing field ordering, the conditional use of include_rows ("only when sample row values are needed"), and the per-call non-persistent nature of workspace, which the schema does not emphasize as strongly.

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 ("Inspect one hosted tabular file") plus the precise output purpose (infer promote-to-dataset column mappings), which separates it from generic preview/list siblings. It stops short of explicitly naming close siblings like whodb_platform_file_preview or whodb_platform_promote_file_to_dataset, so differentiation is inferred from the workflow mention rather than stated.

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

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

Gives explicit timing ("Use this before whodb_platform_action with resource 'file' and action 'promote_to_dataset'") and operational guidance on param selection ("Prefer fields such as [columns, columnMapExample, columnMapFlags] first"). It does not state when NOT to use it (e.g., versus file_preview), leaving one inference gap.

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

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

Annotations already declare readOnly, openWorld and idempotent, so the safety profile is covered. The description adds real behavioral context beyond them: text content is capped in MCP output, tabular previews are returned as the hosted platform provides them, and passing workspace affects only this call without changing defaults.

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

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

Front-loaded purpose followed by tightly packed, actionable guidance. Each sentence carries weight, though the field-name examples are dense enough to read as a run-on rather than scannable 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?

With no output schema, the description partially compensates by explaining return shapes (capped text content, platform-provided tabular previews). Combined with annotations and a fully documented schema, an agent has enough to call the tool correctly, though return-format specifics remain somewhat abstract.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by naming concrete field values ('mimeType', 'sizeBytes', 'isTabular', 'textContent', 'tabular') and clarifying the semantics of the nested workspace object as per-call targeting that leaves defaults untouched.

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 ('Preview one hosted project file'), and 'one' distinguishes it from list-oriented siblings such as whodb_platform_files. It does not, however, differentiate itself from closely related readers like whodb_platform_file_inspect or whodb_platform_tabular_files, so the agent must infer the boundary.

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

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

It gives within-tool sequencing guidance (prefer metadata fields first, request body/row fields only when needed), which is genuinely useful. But it never states when to reach for this tool over file_inspect, file_search, or tabular_files, leaving the sibling choice to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context in 'per-call targeting without changing defaults' and in hinting at the payload shape ('files', 'folders', 'storageUsed'), but says nothing about pagination, result caps, or what a listing returns for a tool with no output schema.

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

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

Four tight sentences, front-loaded with the core action and root-folder default before filters and fields. Nothing is redundant, though the 'fields such as ... needed now' sentence is slightly clunky.

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 6-parameter tool with a nested workspace object and no output schema, the description covers targeting, filtering, and field selection adequately. It is thin on return shape, pagination, and sibling differentiation (e.g., versus file_search or tabular_files), which leaves an agent with unanswered questions before calling.

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 a baseline of 3 is warranted, but the description goes beyond the schema by naming concrete field values ('files', 'folders', 'storageUsed') that the generic 'fields' parameter description does not provide, and by explaining the per-call workspace override intent.

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

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

The description gives a specific verb and resource: 'List folders and files in a hosted project folder,' which is concrete and scope-aware (hosted project). However, it never distinguishes itself from close siblings like whodb_platform_file_search, whodb_platform_file_inspect, whodb_platform_app_files, or whodb_platform_tabular_files, so an agent cannot easily tell which listing tool to pick.

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 offers practical calling guidance (omit folder_id for the root, apply name/kind/mime_type filters 'when known', prefer narrow fields), which is implied usage for the parameters. It gives no guidance on when to choose this tool over the other file-listing/search siblings, so tool-selection guidance is absent.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description's one behavioral contribution is the non-destructive per-call override ('without changing defaults'), which is genuinely useful. It says nothing about result limits, ranking, or search scope, which is thin for an open-world search.

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 tight sentences, and the per-call targeting constraint is stated plainly. No filler, though the second sentence largely restates what the workspace schema already declares.

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 search tool with a full schema and annotations, the essentials are present, but with ~130 siblings including several file tools the description should say what distinguishes a search hit from a file listing and what a result contains. That routing gap leaves the agent to guess.

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 query, fields, and the nested workspace object are fully documented in the schema itself. The description adds nothing about the query string syntax or the meaning of 'top-level output fields'. Baseline 3 applies.

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

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

States a specific verb and resource (search files) and scopes it to 'the selected hosted project'. It does not differentiate itself from the nearby file siblings (whodb_platform_files, whodb_platform_file_inspect, whodb_platform_file_preview), so an agent can't tell from the description alone why it would search rather than list.

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 workspace parameter description does explain the fallback chain ('omit to use the session default set by whodb_platform_session_use, then process/saved defaults') and points at discovery tools. But the top-level description never states when to use search versus listing files, and gives no query syntax or scope guidance.

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