ResearchPilot

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds a genuinely important behavioral fact beyond that: it returns a plan only and 'never claims collection occurred,' which prevents the agent from assuming data was gathered.

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 waste; the plan-only constraint is front-loaded in the second sentence where an agent will see it before calling.

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 plan-only return behavior is well covered and no output schema exists to explain returns. However, with 5 parameters, 0% schema description coverage, and no annotations about parameter meaning, the definition leaves the agent guessing on inputs like period format and targetSize.

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

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

Schema description coverage is 0% across 5 parameters. The enum values (youtube, web, legal, data_api, text_corpus) are self-describing and the description echoes them, but goal, query, period, and targetSize get no explanation — notably 'period' has no format guidance and targetSize has no unit/target 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?

Uses a specific verb ('Build') plus an unambiguous resource ('reproducible collection plan') and enumerates the five supported source categories. Scope is clear enough to distinguish it from search_* or registry siblings, though it never names an alternative tool 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?

Implies when to use it (planning a collection effort across a specified source type) but gives no explicit when-to-use/when-not guidance or routing to siblings like search_datasets or search_literature. The agent must infer the boundary.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only the notion of 'canonical authority' (i.e., this is the source of truth), without covering return shape or freshness of the capability data.

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 zero filler, and the purpose is front-loaded ahead of the usage trigger. Every clause earns its place.

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

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

For a zero-param, no-output-schema read tool, the description supplies enough to know it returns capability information and when to consult it. The only gap is that the shape of the returned capability data is left implicit.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. Nothing in the description is needed or misleading on this dimension.

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 a specific resource ('canonical ResearchPilot capability authority'), and the second sentence scopes what the capability data governs. It is distinguishable from siblings like research_registry or check_method, though 'capability authority' is somewhat abstract phrasing.

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 an explicit trigger condition: use it before claiming ResearchPilot can directly execute a research method. It does not name an alternative tool or state when not to use it, but for a zero-param prerequisite lookup the when-condition 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds that the call yields a five-way classification, but the terms 'certified core' and 'registered engine' are never defined, and with no output schema the agent gets no sense of result shape or behavior on an unknown/invalid capabilityId.

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

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

A single compact sentence with the operation front-loaded and no filler. The trailing five-item enumeration is information-dense jargon, but it is the substantive content rather than padding.

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

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

For a one-param read tool with annotations covering safety, the essential shape is present and no output schema is needed to describe returns. However, the five classification labels are left undefined and there is no indication of where capabilityId values come from, both of which an agent needs to call this 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?

Only one parameter, and schema description coverage is 0% – capabilityId carries no description, constraints, or example in the schema. The description says only 'canonical capability ID', repeating the name without explaining the format, where to obtain a valid ID, or what happens on a miss; it does not compensate for the coverage gap.

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: check one ResearchPilot capability by canonical ID, and it names the classification outcome (discussion/planning, direct execution, certified core, registered engine, specialist handoff). This is far more than a restatement of the name. It stops short of 5 because it never distinguishes itself from the sibling researchpilot_capabilities, leaving ambiguity about which one to call.

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

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

Usage is implied: consult this when you need a routing verdict for a single capability ID rather than a catalog. There is no explicit when-to-use/when-not, no mention of researchpilot_capabilities for enumeration or researchpilot_prepare_specialist_execution for the follow-on action, and no stated prerequisite that the ID must come from the capabilities listing.

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 destructiveHint=false, so the safety profile is covered. The description usefully adds that categories 'remain researcher proposals' and that output is 'bounded,' clarifying this returns a plan rather than committing a final codebook. It does not state whether the skeleton is persisted or returned only, which is the one behavior an agent would still want given a readOnly 'Create' verb.

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 dense sentences with no filler, and the artifact being produced is front-loaded in the first clause. The long noun stack after 'with' is compact but slightly hard to parse on a skim.

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 three-parameter generator with a full set of annotations and no output schema, the description enumerates the components of the artifact and the proposal-only status. The remaining gap, parameter meanings, is captured under parameter semantics rather than a missing-output or missing-safety concern.

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

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

Schema description coverage is 0% and the description mentions none of the three parameters. The meaning of approach (deductive/inductive/hybrid), codingMode (human/ai/hybrid), or how researchQuestion shapes the codebook is left entirely to the enums and defaults, so the description does not compensate for the schema gap.

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 artifact: create a bounded content-analysis codebook and validation skeleton, enumerated as sampling/coding/context units, category contracts, pilot coding and validation requirements. That distinguishes it from siblings like researchpilot_text_analysis_pilot or researchpilot_build_collection_recipe, though it never names an alternative explicitly.

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

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

No guidance on when to call this versus researchpilot_text_analysis_pilot, researchpilot_check_method, or researchpilot_build_collection_recipe, and no stated prerequisites (e.g., an existing project or research question already registered). The agent must infer sequencing from the workflow itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the OAuth-connection scoping, which is useful but modest additional context; with an output schema present it needn't describe return fields.

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

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

Two sentences, front-loaded with the action and scope, followed by the usage restriction. Every sentence earns its place with no redundant restatement of the name.

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

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

For a no-argument read tool with full annotations and an output schema, the description covers scope and intended use adequately. A note on behavior when no profile/OAuth connection exists would close the remaining gap.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies no inputs are required and ties behavior to the connection identity instead of an argument.

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 ('Return the authenticated ResearchPilot user profile') and scopes it to the current OAuth connection. It also distinguishes itself from research-data siblings by ruling out use as research evidence, so an agent can tell it apart 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?

Explicitly says when to use it (user identity/personalization) and when not to (as research evidence). It doesn't name a concrete alternative sibling such as researchpilot_get_user_memory or researchpilot_list_projects, which keeps it from 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, idempotent, non-destructive and closed-world, so the description doesn't need to repeat the safety profile. It does add genuinely new context: the read is scoped to 'one authenticated user's' data, and it explicitly discloses negative space — raw local research files are intentionally absent — which prevents the agent from expecting file contents.

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

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

One dense sentence, front-loaded with the verb and scope, with no filler. It is somewhat list-heavy, but every enumerated item conveys what the caller will receive.

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 carries the burden of describing return content, which it does thoroughly. However, it lacks any routing guidance or prerequisite (how to get a valid projectId), which an agent needs to invoke it correctly in a 22-tool suite.

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

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

Schema description coverage is 0%, so the single projectId parameter is documented only by a UUID regex pattern. The description never describes what projectId refers to or where to obtain it (presumably from researchpilot_list_projects), but the parameter is a single self-evident identifier, so the practical gap is modest.

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 (cloud ResearchPilot project state) and enumerates the contents returned: research question, decisions, summaries, stale state, source digests, artifact availability. It is clearly a read-context tool rather than a list or search tool, though it never names the siblings it differs from (e.g. researchpilot_list_projects, researchpilot_get_profile).

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 use this tool, when not to, or which sibling to reach for instead (for example list_projects to find a projectId first, or get_user_memory for cross-project memory). An agent must infer usage entirely from the name and content list.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: the history is 'bounded' and the data are 'workflow/presentation signals, never scientific authority' — a useful trust/scope signal for downstream reasoning about the returned data.

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 waste, and the scope statement (what is read) is front-loaded before the caveat about data authority. Every sentence earns its place.

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

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

With no input parameters, no output schema, and annotations covering the safety profile, the description needn't explain return values. It conveys the nature and trust level of the returned memory adequately; only the exact shape of 'routing history' is left implicit, which is acceptable given the absence of an output schema.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4; no syntax or scoping details are missing.

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 (the authenticated user's working preferences and bounded routing history), which is clearer than the bare tool name. It does not explicitly differentiate itself from the nearby sibling researchpilot_get_profile, so an agent must infer which of the two holds 'preferences' versus 'profile' data.

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

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

Usage is only implied: 'working preferences and bounded routing history' signals the retrieval context, and the note that these are never scientific authority hints at a supporting, non-primary role. No explicit when-to-use, when-not, or named alternative (e.g., get_profile or update_user_preferences) is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond them: the snapshot is immutable, the evidence catalog excludes source bodies, and the read does not authorize execution — a non-obvious boundary for an agent that might assume reading context grants execution rights.

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: the positive scope first, the negative boundaries second. 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?

No output schema exists, and the description sketches the return only qualitatively ('evidence catalog without source bodies'). Combined with an opaque nested-object parameter, an agent still lacks the handoff's provenance and shape, which is a real gap even though the safety semantics are complete.

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

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

Schema coverage is 0% and the single parameter is an untyped nested object with no declared properties, so the description carries the burden. It identifies what the object is ('the ResearchContext snapshot carried by a ResearchPilot handoff') but never says how an agent obtains that handoff or what keys it contains, so compensation is partial.

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 (immutable ResearchContext snapshot from a handoff) plus scope ('evidence catalog without source bodies'). This implicitly separates it from researchpilot_read_handoff_evidence (which presumably returns bodies), but neither that sibling nor researchpilot_handoff_summary is named, so discrimination is left to inference.

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

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

The description defines what the tool will not do ('does not mutate Studio state or authorize execution'), which implies when it is safe to call, but it gives no positive trigger condition and does not say when to prefer researchpilot_handoff_summary or researchpilot_read_handoff_evidence.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely new behavioral facts: the output excludes source bodies and validation is anchored to the original handoff package. It stops short of saying what 'outer identity' validation actually checks or what a failed validation looks like.

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 tightly packed sentences with the action front-loaded and no filler. It is dense to the point of jargon ('outer ... identity'), but every clause carries information and nothing is 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?

With a nested object parameter at 0% schema coverage, no output schema, and no annotations-specific gaps to hide behind, the description should define the handoff package shape and the summary's bounds. It gestures at both ('bounded', 'original ... as the authority') without resolving either.

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

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

There is a single required parameter, 'handoff', typed only as a bare nested object with 0% schema description coverage and no visible structure. The description says to treat the original handoff package as authoritative but never explains what fields the object must carry or how an 'original' package is distinguished from a modified one, so the agent cannot construct a valid call from the 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?

The description pairs specific verbs with specific resources ('validate the outer ... handoff identity', 'return a bounded context summary'), which is well beyond restating the name. The phrase 'without source bodies' implicitly differentiates it from read_handoff_evidence, though the sibling contrast is only implied rather than named.

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 the original handoff package as the authority' is a correctness constraint, not usage routing. Nothing says when to call this versus researchpilot_handoff_context, researchpilot_read_handoff_evidence, or researchpilot_validate_specialist_receipt, leaving the agent to infer selection from names 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: results are scoped to the authenticated user, restricted to active projects, and ordered newest first. It omits pagination or result-count limits, which is the only substantive gap.

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

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

Two sentences with zero filler. The resource and scope come first, then the usage rule, so the most decision-relevant information is front-loaded.

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

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

For a zero-parameter, read-only list tool with full annotation coverage, the description supplies scope, ordering, and a usage trigger, which is close to everything an agent needs. The remaining gap is how many projects come back and how to page, which matters if the agent must choose among many.

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

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

The tool takes zero parameters, so there is no parameter meaning to document and the schema is trivially complete. Baseline 4 applies; the description correctly adds no invented parameter detail.

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

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

States a specific verb and resource ('List ... ResearchPilot projects') and adds scope ('authenticated user's active', 'newest first'), which lets an agent distinguish it from get_project_context or research_registry. It does not explicitly name a sibling, so it falls just 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?

Gives a concrete trigger: call this before choosing a project when a user phrase like 'my study' is ambiguous. That is a clear when-to-use, but it stops short of naming the alternative to call once the ambiguity is resolved, and there is no when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds meaningful semantic context beyond that: these artifacts must not be treated as researcher-approved canonical decisions, which shapes how downstream results should be used. It omits ordering, volume, or pagination behavior for a list operation.

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, and the core action plus scope is front-loaded before the usage guidance. Every clause adds either scope or interpretation guidance.

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 would ideally hint at what a listed artifact contains (identifiers, types, timestamps) so an agent knows it can feed an ID into read_work_artifact. The caveat about non-canonical status is valuable, but the shape of the result set is unaddressed.

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 0%, so the description has to carry the parameter burden. It contributes the notion of 'one authenticated project' and single-project scoping, but projectId's UUID format and the fact that it is the sole required parameter are left entirely to the schema.

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

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

States a specific verb and resource ('List saved working artifacts') scoped to one project, which cleanly separates it from the singular read_work_artifact and the mutating save_work_artifact siblings. The added clause about treating artifacts as non-canonical gives the resource a precise identity an agent can act on.

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

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

'Use this to continue prior host-AI plans, interpretations, critiques, or drafts' gives a clear when-to-use trigger tied to resuming prior work. It stops short of naming explicit alternatives (e.g., read_work_artifact for a single artifact) or stating when not to call it.

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 destructiveHint=false, so the safety profile is covered. The description adds that the workspace is interactive and is meant to precede continuation of the host conversation, which is useful. It does not disclose what actually happens on invocation — whether it blocks, returns control to the user, yields a workspace handle, or produces any output — which matters for a UI-launching 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?

A single front-loaded sentence with no filler; each clause contributes either the action or a trigger. The trailing list of user intents makes it slightly run-on but every item adds routing value.

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 parameters, no output schema, and annotations that already cover safety and idempotency, the only remaining burden is telling the agent when to invoke it — which the description does explicitly. Nothing essential to 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?

The schema has zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies all context comes from the host conversation rather than arguments.

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 ('Open the interactive ResearchPilot workspace') and enumerates the concrete actions available inside it (select project, inspect capability, review context, edit instruction). It is clearly distinct from sibling read tools such as get_project_context or list_projects, though it never names a sibling to sharpen 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?

Gives an explicit trigger condition — 'when the user wants to select a project, inspect method capability, review research context, or edit an instruction' — plus the framing 'before continuing in the host AI conversation'. That is clear usage context, but it does not say when NOT to use it or name the alternative tools (e.g., get_project_context) that cover overlapping needs programmatically.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-behavior ('does not execute the analysis or transfer local raw files'), but omits what the call actually produces (a request handle? a receipt?) and never mentions that repeat calls are not idempotent per idempotentHint=false.

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

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

Two sentences, front-loaded with the action and followed by the key exclusion; nothing is padded. The density of undefined terms costs readability but not length.

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

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

For a five-parameter, zero-coverage, no-output-schema tool this is thin. An agent cannot learn what the prepared request looks like, how rigor affects rigor of validation, or how the digest bindings are supplied, so it may call the tool without the information the call conceptually requires.

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

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

Schema description coverage is 0% across five parameters, so the description must carry the burden and does not. It never explains rigor's three levels, the difference between requiredOutputs and requestedWork, or where the referenced digests come from - in fact it names digests that are not parameters at all, which invites confusion.

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 ('Prepare a rigorous specialist execution request') and enumerates the binding context (project, ResearchContext digest, capability authority, artifact digests). It is distinguishable from validate_specialist_receipt by the 'does not execute the analysis' boundary, though the dense jargon ('capability authority') clouds the plain action.

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 and no named alternatives among the many siblings (validate_specialist_receipt, researchpilot_capabilities, text_analysis_pilot). The only routing signal is a negative one ('does not execute'), which hints at a preceding step without naming it.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds the digest-verification precondition and the 'one exact page' paging notion, but doesn't say what happens on digest mismatch, how errors surface, or how large a page is.

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

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

A single dense sentence that front-loads the action and then the precondition. Every clause carries information, though the phrasing is jargon-heavy enough to slow a first read.

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

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

For a tool with a nested object parameter, 0% schema coverage, no output schema, and a digest-verification step, the description is too thin. It never defines what a handoff is, what the evidence page contains, or how verification failure is communicated, so an agent cannot fully predict call outcomes.

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

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

Schema description coverage is 0% and one parameter (handoff) is an undocumented nested object, so the description carries the full burden. It gestures at 'handoff', 'source digest', and paging via 'one exact evidence page', but never explains what sourceId identifies or what offset does, leaving the core inputs ambiguous.

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 ('Read one exact evidence page from a ResearchPilot handoff'), which is concrete enough to act on. It doesn't explicitly differentiate from nearby siblings like researchpilot_read_work_artifact or researchpilot_handoff_summary, so an agent must infer which retrieval path 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?

The clause 'after verifying the outer source digest against the immutable ResearchContext snapshot' gives a precondition for use, which is genuinely useful. However, there is no guidance on when to choose this over read_work_artifact or handoff_summary, and no statement of when it should not be used.

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, non-destructive, and closed-world behavior. The description adds meaningful context by stating the ownership check on both project and artifact, but it does not say what happens on verification failure (error shape) or what the artifact contains.

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

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

A single front-loaded sentence that carries the action and the key precondition without filler. Slightly dense but 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?

There is no output schema, so the description would need to explain the return value, and it does not say whether the artifact's content or just its metadata is returned. It also leaves the failure mode of the ownership check unspecified.

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

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

Schema description coverage is 0%, so the schema only provides UUID patterns for projectId and artifactId. The description adds semantic value by clarifying that both the project and the artifact must belong to the authenticated owner, but it does not explain the relationship between the two IDs or what either represents beyond that.

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 ('Read one saved working artifact') and clarifies it returns a single artifact, implicitly distinguishing it from the sibling list_work_artifacts and save_work_artifact. It does not explicitly name those alternatives, but the singular scope is clear enough for selection.

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 precondition (ownership verification must pass) but gives no explicit when-to-use vs when-not guidance and names no alternatives. Usage is implied from the 'read one' scope 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 this is a non-read-only, non-destructive, non-idempotent write, so the mutation profile is visible. The description adds useful guardrails (only on explicit user feedback, don't persist question/source text), but says nothing about what is persisted, duplicate handling for the non-idempotent write, or what happens to prior feedback.

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 core action, followed by the invocation condition and the data-handling constraint. Nothing is wasted.

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

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

For a six-parameter mutation tool with zero schema descriptions and no output schema, the description leaves the key required field taskFamily undefined and does not indicate the return value or persistence behavior. It covers triggering but not the information an agent needs to populate the call 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 0% across six parameters, so the description must carry the semantics and largely does not. The outcome enum values are inferable from the accept/reject/correct/failure wording, but the required taskFamily parameter — the most ambiguous field — is never explained, nor are projectId, capabilityId, or toolName.

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: recording explicit user feedback about a ResearchPilot capability/tool outcome. It is clearly distinct from siblings like update_user_preferences or save_work_artifact, though it never names an alternative explicitly.

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

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

Gives a firm trigger condition — call only when the user explicitly accepts, rejects, corrects, or reports success/failure — which is a genuine when-to-use rule. It adds a negative constraint about not storing the research question or source text, but offers no alternative tool routing or exclusion against other persistence 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, destructiveHint=false and openWorldHint=false, so safety is covered; the description still adds real value by warning that a registry hit does not authorize execution or collection, and by labelling plugins as 'planned' (i.e., not yet usable). It says nothing about result volume, pagination, or how `limit` affects returns.

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 resource and its four variants, then the one behavioral caveat that matters. Zero filler and nothing repeated from the schema or annotations.

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 this covers intent and the permission boundary, but with no output schema the description never indicates what a registry entry looks like (ids? names? capability flags?), which matters because results presumably feed into researchpilot_prepare_specialist_execution. Adequate but leaves the return shape entirely unstated.

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

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

Schema description coverage is 0%, so the description carries the burden. It partially compensates by expanding the four `kind` values (method/model, source-provider, official-reference, planned-plugin), which is genuinely useful for the enum. The `query` and `limit` parameters receive no semantic treatment at all — no hint that query is an optional free-text filter or that limit caps entries returned.

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 verb 'Search' plus the specific resource (a unified registry of methods/models, source providers, references, or planned plugins) maps directly onto the four `kind` enum values, so an agent can tell it apart from siblings like researchpilot_search_datasets or researchpilot_search_literature. It stops short of naming those siblings explicitly as alternatives.

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?

'Planning/discovery only; registry presence never authorizes execution or collection' gives a clear usage context and a meaningful boundary — it tells the agent this is a lookup step, not an execution step. No alternative tool (e.g. researchpilot_check_method for validating a specific method) is named, so routing between siblings is still 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?

The annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is largely covered. The description usefully adds that the artifact is non-canonical and does not constitute a decision or execution authorization, but it says nothing about the consequences of the non-idempotent flag (e.g. that repeated saves create distinct artifacts) or about retention/visibility of what is stored.

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, and the definitional statement precedes the constraint. Each clause adds information an agent cannot get from 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 six-parameter write tool with no output schema and no parameter documentation, the description covers intent and the decision/execution boundary but leaves the return value (presumably an artifact id), the meaning of `contextDigest`, and duplicate-save behavior unaddressed. It is adequate at the conceptual level and thin at the operational level.

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

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

Schema description coverage is 0% across six parameters, five of them required, so the description must carry the load. The content-kind list loosely maps to the `kind` enum, but nothing explains `contextDigest` (a required, 200-char string), `projectId` format expectations, `sourceRefs`, or the 200k-char `text` limit — an agent must guess at the most consequential required field.

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 ("Save") plus a resource ("WORKING artifact") and enumerates the accepted content kinds (plan, interpretation, critique, draft, specialist result), which lets an agent distinguish it from read_work_artifact and list_work_artifacts. It also distinguishes the artifact from canonical research decisions, though it never names a sibling tool directly.

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 for durable ResearchPilot continuity" gives a positive trigger, and "this never accepts a research decision or authorizes execution" gives an explicit exclusion. It stops short of naming which tool should be used instead for decisions or execution authorization, so the routing on the negative side is implied rather than complete.

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 non-destructive. The description adds one meaningful behavioral caveat: results are source candidates, not dataset-fit approval, which warns against over-trusting output. It never explains what an 'availability state' looks like or how missing providers are represented.

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 action front-loaded and the caveat placed second where it reads as a qualifier. No filler, though it is arguably too terse for the information the agent needs.

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?

Placeholder.

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

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

Schema description coverage is 0%, so the description carries full burden, yet it mentions neither the query parameter nor the scope enum (korean/international/all). Since there is no output schema explaining the returned records, the scope filter's effect on results is entirely undocumented.

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: searching dataset/data-paper providers. The phrase 'explicit provider availability states' implies the domain differs from researchpilot_search_literature, but the sibling is never named, so differentiation is inferred 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?

No guidance on when to prefer this tool over researchpilot_search_literature or researchpilot_research_registry, and no prerequisites or exclusions. The agent must guess which search surface fits a dataset request.

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, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so safety and mutability are covered. The description adds genuinely non-redundant behavior: it names the external adapters and explicitly warns that results are bibliographic, not scientific-quality or full-text verification — an important limitation on what the agent can conclude from a hit.

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

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

Two sentences, front-loaded with the action and the underlying data source. The second sentence is a compact scope caveat and nothing in the definition is 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 read-only search tool with no output schema, the definition covers what is searched and the verification boundary, which is useful. However, it leaves out what a result record contains, ordering/relevance behavior, and whether pagination or result-count parameters are absent by design, so an agent still guesses at the return 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 0% and the description says nothing about how the single 'query' parameter is interpreted — free-text, Boolean syntax, fielded search, or length behavior. The parameter name and the purpose sentence make its intent reasonably obvious, so it avoids the low score of a fully undocumented multi-param tool, but it does not compensate for the coverage gap.

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 ('Search') and resource ('research literature') and names the backing adapters (OpenAlex/Crossref), so the agent knows exactly what corpus is being queried. It does not explicitly contrast with the literature-adjacent sibling researchpilot_search_datasets, leaving that differentiation to inference.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative such as researchpilot_search_datasets for dataset lookups. The only usage-shaped statement is a negative caveat about what the results do not verify, which constrains trust but does not route the agent between 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, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds genuinely useful scope context ('Design only; no coding or validation is claimed') clarifying that no execution/validation side effect occurs, but it says nothing about the shape, size, or structure of what is returned beyond listing component names.

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 deliverable list front-loaded and the critical 'design only' caveat placed last for emphasis. No filler; every clause identifies a concrete artifact or constraint.

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 does useful work by enumerating the return-package contents (recipe, codebook skeleton, manifest, plan, AG-UI state, handoff route). However, for a 9-parameter tool with 0% schema coverage, it leaves several inputs (targetSize, period, codingMode, approach) unexplained, so an agent cannot fully reason about invocation 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 description coverage is 0% across 9 parameters (including three enums: approach, codingMode, sourceType), so the schema itself gives no property-level meaning. The description's component list loosely maps to parameter groups (collection recipe ∼ query/period/sourceType, codebook skeleton ∼ categories/approach, corpus manifest ∼ corpusItems), providing some implicit guidance, but targetSize, codingMode, and enum semantics are never explained.

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 ('Create') and a concrete, bounded resource ('text-analysis pilot package') and enumerates its components (collection recipe, codebook skeleton, corpus manifest, plan, handoff route), which is far more than a name restatement. It does not, however, explicitly differentiate itself from siblings like researchpilot_build_collection_recipe or researchpilot_prepare_specialist_execution whose outputs are named as sub-components here.

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 'bounded' pilot package and 'Design only; no coding or validation is claimed' imply the tool's scope, and there is a hint it precedes actual execution. But it never states when an agent should choose this versus build_collection_recipe or content_analysis_template, and no prerequisites or exclusions are given.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive and closed-world. The description adds genuinely non-derivable context: preferences affect presentation/workflow only and never scientific authority or method validity, plus the 'bounded' scope. It does not explain merge semantics for omitted or null fields, which is the main remaining gap.

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

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

Two sentences with no filler; the invocation gate leads and the safety boundary follows. Nothing is redundant with the annotations.

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 nine-parameter mutation with no output schema and no field descriptions, the description should say whether this is a partial update and what happens to unspecified fields. It covers purpose and safety but leaves an agent unable to predict the effect of the call on existing preferences.

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

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

Schema description coverage is 0% across nine parameters, so the description carries the full burden and says nothing about any individual field. It never clarifies that all fields are optional, what a null value does (clear vs. leave unchanged), or how citationStyle's free-form string is used. The self-descriptive names and four enums help, but the compensation is far too thin.

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

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

The description names a specific verb and resource (update working/writing preferences) and scopes it to a 'bounded' preference set, which separates it from memory- or profile-oriented siblings. It stops short of naming which sibling to use when the intent is to read preferences rather than write them.

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

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

It gives an explicit gating condition: only call when the user explicitly states a stable preference. That is a clear when-to-use rule, though no when-not or alternative (e.g. get_profile / get_user_memory) is named for read or exploratory cases.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by enumerating what the validation checks (identity, input digests, sample accounting, diagnostics, validation-state structure) and by explicitly disclaiming independent scientific-correctness validation. It does not describe failure behavior or return format, but it adds substantial scope 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?

The description is two tightly written sentences with no wasted language. The primary action and scope are front-loaded, and the limitation is clearly stated afterward.

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

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

The description explains the validation scope and its main limitation, which is useful for a complex receipt-checking tool. However, with two nested object parameters, zero schema coverage, and no output schema, it leaves important gaps: what the request and receipt objects should contain and what the validation result looks like. It is adequate but not complete for an agent to invoke confidently.

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?

Both parameters are required nested objects with 0% schema description coverage, so the description carries the full burden of explaining them. It refers to a request and a receipt, which identifies their roles in the validation, but it provides no structural detail, expected fields, or minimum content for either object. This is a significant gap for two nested-object parameters.

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: validate a specialist execution receipt against its ResearchPilot request and authenticated project/context identity. It also clearly scopes the check by listing what is verified and explicitly excluding independent scientific-correctness validation. It does not directly name sibling tools, but the operation is specific enough to distinguish it from preparation or evidence-reading siblings.

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

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

Usage is implied by the validation workflow: this tool is for checking a specialist receipt against its originating request and identity context. The description notes a boundary (it does not validate scientific correctness), which helps avoid misuse, but it does not explicitly state when to call it, prerequisites such as a prior execution step, or an alternative tool for correctness checks.

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