Hypotize

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: the required role (contributor/editor/owner) and the side-effect boundary that updated_at is untouched.

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 role/side-effect caveats trailing. 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?

Auth and side-effect behavior are covered, and no output schema means return values need no explanation. However, for a three-parameter mutation with zero schema descriptions and no output schema, leaving every parameter undocumented is a real 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 0% and the description names none of the three parameters. The non-obvious idempotency_key (and its 8-200 char constraint) and the content limit go entirely unexplained, and 'dated' hints at a date field the caller cannot supply.

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 a dated comment to an experiment') and no sibling tool offers comment creation, so the agent can place it immediately. The parenthetical example ('an interim reading while the test is Running') further pins down intent.

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 usage scenario (interim reading during a running test) and implicitly separates itself from hypotize_experiment_update by noting it does not change updated_at. It stops short of naming an alternative tool or stating when not to use 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 declare destructive, idempotent and non-read-only, and the description substantiates them: items left out are deleted, updated_at changes, optimistic concurrency via expected_updated_at, and role-based authorization errors. It also discloses the return value (the plan and its total hours), adding context beyond the hints.

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-loads the replace semantics and the sibling differentiation, then layers constraints, error codes and return value in short declarative sentences. Dense but every clause carries operational information with 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?

Even without an output schema, it states what is returned, what is destroyed, what errors arise, and what authorization is needed. For a destructive whole-collection replace with four required params, this covers everything an agent needs to call it safely.

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 load. It explains the items array well, including the keep/new/delete semantics of a nested id, but experiment_id and idempotency_key are never discussed and expected_updated_at is only implied through the STALE_EXPERIMENT concurrency note.

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 ('Replace the whole action plan of an experiment') plus the concrete payload (task list with title, estimated_hours, assignee_id, completed). It also explicitly separates itself from hypotize_experiment_update, which it says does not touch the action 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?

Gives the full replace contract: which items to keep (id present), add (id absent), and remove (omitted entirely). It also names preconditions (assignees must be project members; editor/owner role required) and the failure modes (STALE_EXPERIMENT, INSUFFICIENT_ROLE with required_roles).

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the required hypotize:delete scope at connection time, the editor/owner role requirement, and the exact failure mode (INSUFFICIENT_ROLE with required_roles) for contributors/viewers.

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, each earning its place, with the destructive nature and the hard prerequisites front-loaded before the error detail. No filler or restatement of the tool 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 destructive two-parameter delete, the description covers permanence, auth scope, role gate, and error behavior, which is most of what an agent needs. The remaining gap is the idempotency_key contract (retry/replay semantics) and whether deletion cascades to dependent records.

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% for two required parameters, and the description explains neither. experiment_id is self-evident, but idempotency_key carries real semantic weight (replay/retry behavior for a destructive call) that is documented nowhere in the schema or the description, so the gap is not compensated.

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 ('Permanently delete an experiment') and the permanence qualifier immediately rules out reversible alternatives like update or transition in the sibling set. An agent can distinguish it from hypotize_experiment_update or hypotize_experiment_transition without opening any 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?

The description states prerequisites (scope and role) but never says when to choose this tool over alternatives such as archiving, transitioning, or updating an experiment. Usage is implied by the delete semantics rather than explicitly framed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without description help. The description does add genuine context beyond the annotations: the result is scoped to what the caller's project is authorized to see, and writing_instruction is only present 'when the project has one'. Error behavior for unauthorized or missing experiments is not 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?

A single dense sentence with no filler, and the core action is front-loaded. The trailing parenthetical defining writing_instruction and the conditional clause are somewhat awkward to parse but each 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?

With no output schema, the description does useful work by enumerating the returned components, which is the main reason it is adequate. However, for a get-by-id tool it omits what an agent needs on the failure path (not found, not authorized) and says nothing about the required identifier.

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 one parameter (experiment_id) and schema description coverage is 0%, so the description must carry the explanatory burden. It never mentions the id, its UUID form, that it is required, or how to obtain one, leaving the only input completely unqualified in prose.

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 (Get) and resource (a project-authorized experiment) and enumerates the payload it returns (vote aggregate, action plan, recent comments, writing_instruction). It distinguishes itself implicitly from hypotize_experiments_list by fetching a single experiment, though it never names the contrasting 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?

Usage is implied rather than stated: an agent can infer this is the single-experiment fetch versus hypotize_experiments_list, but no explicit when-to-use, when-not-to-use, or alternative routing is given. There is also no guidance on prerequisites such as the caller needing project authorization.

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 flag destructiveHint=true; the description explains exactly what that means — replace semantics where omitting next_steps or evidence_links clears them — which is precisely the context annotations cannot convey. It further discloses role requirements (editor/owner), optimistic concurrency (STALE_EXPERIMENT), and specific error codes with their triggering conditions.

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 purpose and the key atomicity constraint, then routed through usage alternatives and validation rules. Dense but each clause carries new information; the parenthetical error codes add length that could be compressed but not removed without losing diagnostic 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?

For an 11-parameter destructive mutation with no output schema, the description covers safeguards, role gating, status/result invariants, and sibling routing. It is silent on what the call returns and on idempotency_key behavior, which are the remaining gaps an agent might hit.

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

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

With 0% schema coverage the description must carry the load, and it documents 8 of 11 parameters, including the non-obvious coupling between result and final_status and the clearing behavior of optional fields. It leaves idempotency_key unexplained and doesn't tie expected_updated_at to the STALE_EXPERIMENT behavior, so the coverage is strong but not complete.

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+resource ('Record how an experiment ended') and explicitly claims uniqueness: 'It is the only tool that sets result.' An agent can distinguish it from hypotize_experiment_update and hypotize_experiment_transition 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?

States the typical invocation context ('Usually called in Analyzing with final_status'), the consequence ('closes the test in the same call'), and explicitly rules out the sibling ('hypotize_experiment_transition is then not needed'), plus names the alternative for corrections ('use hypotize_experiment_update'). When-to-use and when-not-to-use are both present.

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

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

With annotations covering only read/write/idempotency hints, the description carries the load and delivers: atomic rollback behavior, the exact permission requirement and resulting INSUFFICIENT_ROLE error with required_roles, framework defaulting, status-alias coercion (Testing/Analysis), result-mapping rules, and a full error taxonomy. This is exactly the behavioral context annotations cannot express.

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

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

The core promise (batch size, atomicity, error naming) is front-loaded in sentence one, followed by permissions and then validation rules. It is a dense single paragraph, but given the volume of error codes and lifecycle rules it is appropriately sized; a bulleted structure would have aided scanning.

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 nested-array import with no output schema, the description covers permissions, validation per status, coercion rules, and errors thoroughly enough to construct a valid call. It omits what a successful response returns (created IDs, per-row results) and the practical meaning of reusing an idempotency_key, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the highest-risk fields: scores keys must match the framework (ICE impact/confidence/ease, PIE potential/importance/ease, RICE reach/impact/confidence/effort), result/status interactions, winner_variant validation, and idempotency_key reuse. It does not cover funnel, short_idea, tags, or variant constraints, so it falls short of exhaustive.

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 precise verb and resource plus scope: 'Import up to 50 existing experiments atomically,' and immediately explains the all-or-nothing semantics. That distinguishes it from the single-record siblings, but it never explicitly names an alternative (e.g., repeated hypotize_idea_create or hypotize_experiment_update), so it stops short of full sibling differentiation.

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

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

The description gives prerequisites (editor/owner role) and validation conditions that implicitly define when a batch will succeed, but it never states when to prefer this tool over creating experiments one at a time or over the other experiment tools in the sibling list. Usage context is implied by the word 'import' rather than argued.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious domain behavior: Ideas are experiments in the Idea status rather than a separate object, and Testing/Analysis are legacy aliases of Running/Analyzing. It omits result ordering and pagination behavior, which keeps it from a 5.

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

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

Two compact sentences, front-loaded with the core operation, followed by only the disambiguating domain notes that an agent cannot get from the schema. No filler.

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

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

With seven parameters, no output schema, and zero schema description coverage, the definition should at minimum explain the filter parameters and cursor-based pagination. It covers the status-naming pitfall well but leaves the filtering and paging model entirely to inference.

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 must carry the burden. It partially does: the note that Testing and Analysis are legacy names directly explains the statuses enum values and warns the agent it may need to filter on either spelling. However, tags, funnel, updated_after, limit and cursor receive no semantic explanation at all.

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 with scope: 'List the project-scoped experiment backlog and pipeline'. It also clarifies that Ideas are included, which preempts a likely misreading. It stops short of naming sibling tools like hypotize_experiment_get for single-record retrieval, which is the one remaining differentiation gap.

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: this is the tool for enumerating experiments within a project. There is no explicit statement of when to prefer it over hypotize_experiment_get or hypotize_learnings_list, and no guidance on paging through results; the agent must infer that from the schema.

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

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

Annotations only cover readOnly=false, idempotent=true, destructive=false, which is minimal. The description adds the state-machine semantics, that moving back to an open status clears the result, that leaving Running sets ended_at, that it writes no definition or outcome text, that it uses optimistic concurrency, and it names the role requirement plus every error code an agent may need to branch on.

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?

It is long but front-loaded: purpose, then transition rules, then the sibling alternative, then error conditions. Nearly every sentence carries operational information, though the error-code list is dense enough that the key routing advice (use record_outcome to close a test) competes with it.

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

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

With no output schema and a mutation tool, the description does the heavy lifting on side effects, failures, and permissions. The only real omission is the purpose and format of idempotency_key, which matters for a retryable write operation.

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% for four required parameters. The description explains to_status thoroughly and implies expected_updated_at via the STALE_EXPERIMENT concurrency note, but idempotency_key is never mentioned and experiment_id semantics are assumed, so half the parameters remain 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?

"Move an experiment to another status" gives a specific verb and resource, and the following sentences delimit exactly which statuses are reachable and under what conditions. It is clearly separable from hypotize_experiment_record_outcome, which is explicitly named as the different tool for closing a test.

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 spells out the allowed forward path, the backward-move rules, and the jump-to-Archived case, then says "To close a test, call hypotize_experiment_record_outcome instead" with the reason (that tool writes result and outcome text in one call). Prerequisites for Ready and final statuses are enumerated, so an agent knows when this tool will fail before calling 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 declare a mutating, idempotent operation, but the description adds behavior the annotations cannot express: optimistic concurrency with a STALE_EXPERIMENT failure, the OUTCOME_REQUIRED invariant that a closed experiment keeps non-empty actual_result and learning_summary, and role-based failure (INSUFFICIENT_ROLE with required_roles). These are exactly the constraints an agent needs before invoking a destructive update.

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 exclusions, then concurrency and permission failure modes — every sentence carries operational weight. Slightly dense in the middle (field enumeration plus three sibling redirects), but 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 destructive, nested-payload mutation with no output schema, the description covers the safety-critical pieces: concurrency, invariants, permission failure, and sibling boundaries. The remaining gaps are partial-update semantics and the idempotency contract, which an agent may need 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 description coverage is 0% on a nested 20-field patch object, so the description must carry meaning, and it does explain the otherwise cryptic required expected_updated_at (pass the value from the last read) and which field groups are editable versus forbidden. It still doesn't spell out patch merge semantics (omitted fields unchanged) or what idempotency_key should contain, so it is strong but not exhaustive.

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

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

States a specific verb (update), the target resource (an experiment in any status, including Ideas), and enumerates the classes of editable fields (definition fields plus outcome text such as actual_result, learning_summary, winner_variant). It also explicitly names what it does NOT change (status, result, action plan) and which siblings own those, so an agent can distinguish it from hypotize_experiment_transition and hypotize_experiment_record_outcome without opening a 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 explicit routing: use hypotize_experiment_transition to move status, hypotize_experiment_record_outcome to record the outcome, and hypotize_experiment_action_plan_set for the task list. It also supplies the precondition for calling it correctly (expected_updated_at from the last read, editor/owner role), leaving nothing 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 it is a non-readonly, idempotent, non-destructive, closed-world write, so the bar is lower. The description adds real value beyond that: it discloses the authorization requirement (editor/owner) and the exact failure mode (INSUFFICIENT_ROLE with required_roles), which annotations do not cover.

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 followed by the gating constraint. No filler or redundancy; 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 an 8-parameter, 6-required mutation tool with no output schema and 0% schema description coverage, the description covers only the auth path. An agent still lacks guidance on the complex parameters (dimensions array, formula_type enum, formula_config weights) that are central to 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 0% across 8 parameters (6 required), yet the description names none of them. It does not explain dimensions, formula_type/formula_config, label, or the idempotency_key, so it fails to compensate for the coverage gap as required.

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

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

The description states a specific verb (Create) and resource (custom scoring framework) with the distinguishing qualifier 'active custom'. An agent can tell this apart from hypotize_frameworks_list (the only other framework sibling) purely from the description.

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

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

The role requirement ('editor or owner') gives a precondition for use, which is genuinely useful context. However, there is no explicit when-to-use vs alternatives guidance and no exclusion of scenarios beyond the role gate.

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 safety is covered. The description adds real value by disclosing the return scope (only active custom frameworks, built-ins excluded), but says nothing about return shape, ordering, or pagination 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 short sentences, purpose front-loaded, and the exclusion clause immediately follows to bound expectations. 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?

For a single-parameter read-only list tool with no output schema, the description covers purpose and result scope adequately. It could say a bit more about what a returned framework contains, but nothing critical 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?

One parameter with 0% schema description coverage; the description adds no meaning about project_id beyond its self-descriptive name and uuid format. Baseline 3 is appropriate since the lone identifier parameter is near self-evident from 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 the active custom frameworks of a project') and scopes it precisely by excluding the built-in ICE/PIE/RICE frameworks. This clearly separates it from hypotize_framework_create and the built-in framework concept, though it does not explicitly name a 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?

Usage is implied by the scope statement: use this to enumerate a project's custom frameworks. There is no explicit when-to-use/when-not guidance and no pointer to the alternative hypotize_framework_create for creating frameworks, so the routing value is only moderate.

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=false, idempotent=true, destructive=false, so the safety profile is covered; the description adds genuinely non-redundant behavior: initial status is Idea, the returned ID works across hypotize_experiment_* / vote / comment, role-based failure semantics, and framework defaulting when omitted. The notable omission is the required idempotency_key, whose retry/dedup behavior is never explained anywhere.

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 and scope, then progressively adds the import alternative, downstream ID reuse, optional fields, and permissions. Dense but nearly every clause adds decision-relevant information; the parenthetical tool list is the only slightly padded portion.

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?

Strong on identity, alternatives, permissions, and status, but with no output schema and 18 undocumented parameters the agent still cannot tell what most fields mean, what the response body contains beyond an ID, or how idempotency_key affects retries. Adequate for the happy path, incomplete for a create tool of this surface area.

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 18 parameters, so the description must carry the semantic load, and it only names six optional definition fields and the framework default. Required parameters like idempotency_key, funnel (an enum), and short_idea get no explanation, and variants, tags, target_segment, and success_metric are unmentioned entirely.

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

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

States a specific verb and resource ("Create one experiment") and immediately resolves the domain ambiguity that an Idea *is* an experiment, not a separate object. It names the sibling it is not (hypotize_experiments_import) and lists the downstream tools the returned ID unlocks, so an agent can place the tool precisely in the family.

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 alternative with the condition that selects it: use hypotize_experiments_import for a batch or for experiments already past Idea. It also states the permission gate (editor/owner required, contributor/viewer get INSUFFICIENT_ROLE with required_roles), which tells the agent when the call will fail rather than leaving it to discovery.

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 a closed world, so the safety profile is covered. The description adds two non-obvious behaviors beyond that: results are sorted by most recent update, and setting ended_after silently drops rows lacking ended_at. It does not disclose the default status filter (terminal states only), which materially changes what comes back, nor any pagination behavior despite a cursor parameter.

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 padding; the resource and ordering come first, and the filter caveat follows. Every clause carries information an agent would otherwise have to guess.

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, 0% schema description coverage, and six parameters including a cursor, the description leaves too much unexplained: pagination, how limit interacts with cursor, and what the results/statuses filters accept. It covers ordering and one filter well but is not complete enough to invoke confidently beyond the simplest call.

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 schema names fields without explaining them. The description compensates for ended_after well (timestamp semantics plus the null-exclusion side effect) and hints at project_id via 'project-scoped', but limit, cursor, results and statuses receive no explanation at all, including the consequential default status set.

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 ('List project-scoped experiment outcomes and learnings') plus the ordering rule ('newest update first'), so an agent knows exactly what it returns. It never contrasts itself with the nearby sibling hypotize_experiments_list, so the boundary between 'experiments' and 'learnings' must be inferred from 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?

It gives one concrete usage cue ('use it for a weekly review') tied to ended_after, which is genuinely helpful. It offers no guidance on when to choose this over hypotize_experiments_list, nor any prerequisites for the required project_id, so usage is implied 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=false, destructiveHint=true, idempotentHint=true, so the safety profile is covered. The description adds value beyond that by spelling out scope isolation (own profile only) and the null-clears semantics for company_role. It does not, however, disclose what 'destructive' means here (e.g., overwriting an existing display name), so it stops short of full behavioral disclosure.

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-loads the core action and then layers constraints efficiently; every sentence is substantive. There is mild redundancy between 'the current user's own' and the closing 'only this user's profile, never another member's,' but the rest is tight.

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 with no output schema, the description covers sourcing rules, scope, optionality, and clearing behavior adequately given the annotations already declare idempotent/destructive. The one real gap is the unexplained required idempotency_key, which is a minor omission for an agent that can supply a UUID.

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 most of the burden. It explains 'name' sourcing rules and 'company_role' optionality plus null-to-clear semantics, but the required 'idempotency_key' parameter is entirely unexplained, and length constraints (maxLength 160/200) go unmentioned.

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 ('Set the current user's own display name and, optionally, their role at the company') and explicitly bounds scope with 'Changes only this user's profile, never another member's.' An agent can distinguish it from sibling mutations like hypotize_project_update or hypotize_vote_upsert without opening any 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?

Explicit when/when-not guidance: only use a name the user typed or confirmed, never from email/account/memory/earlier chats; if no name is given, ask first and wait; company_role is optional and null clears it. It also names the exclusion condition (never another member's profile), leaving nothing 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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior beyond them: workspace_id is optional and resolves to the only workspace membership or the personal workspace. It omits error/permission behavior, keeping it from a 5.

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

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

Two tight sentences, front-loaded with the create action and the workspace-targeting rule. No filler, though the second sentence is more about downstream workflow than this 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 10-parameter mutation with no output schema and no annotation-independent documentation of the inputs, the description covers only workspace resolution. Nine parameters, including a required idempotency_key, are left unexplained, which is a substantial 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 0% across 10 parameters, so the description carries the full explanatory burden. It only clarifies workspace_id defaulting and leaves required fields like name and idempotency_key, the framework enum, and the many optional fields 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+resource ('Create a project') and scopes it to a workspace, which cleanly separates it from the read/update/delete project siblings. It does not name an alternative sibling explicitly, so it stops short of a 5.

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

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

The description hints at the lifecycle ('Use its ID to import existing experiments'), which implies the follow-up tool hypotize_experiments_import. However, it never states when to reach for this tool versus project_get/update/list, nor any preconditions, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them: permanent irreversibility and the two authorization requirements (connection-time scope plus owner role). It doesn't say what happens to dependent resources, which keeps it from a 5.

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

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

Two sentences, front-loaded with the action and its permanence, then the permission requirements. No filler and nothing 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 destructive, no-output-schema tool, the description covers permanence and auth but leaves gaps: no cascading-effect disclosure (what is destroyed alongside the project) and no idempotency_key semantics. Adequate as a minimum, notably incomplete for an irreversible operation.

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 full burden for both parameters and explains neither. project_id is reasonably self-evident from the name, but idempotency_key (8-200 chars, how retries are deduplicated) is entirely undefined despite the tool being retry-safe.

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 ('Permanently delete a project'), and the adverb 'permanently' disambiguates from a soft-archive/update operation. It doesn't explicitly name a sibling, but no other sibling deletes a project, so the agent can route to it unambiguously.

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 states prerequisites (hypotize:delete scope granted at connection time, owner role), which tells the agent when the call will be permitted. However, it gives no guidance on alternatives or when deletion is preferable to hypotize_project_update or archiving, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful boundary context beyond annotations: it explicitly scopes the payload to 'non-sensitive' data and notes the conditional presence of writing_instruction. It stops short of explaining auth requirements or exclusion details, but the added scope disclosure is meaningful.

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

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

A single front-loaded sentence with no filler; the core return contents are stated first. The dense parenthetical for writing_instruction is compact and earns its place. Slightly list-heavy but efficient.

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 values, and it does so by enumerating the fields returned. For a simple one-parameter read tool with readOnly annotations, this is largely sufficient, though the exact meaning of 'non-sensitive' and the shape of 'membership summary' remain 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% and the single project_id parameter is not mentioned in the description. Because the parameter is a self-evident UUID identifying the project to fetch, the description does not need to compensate heavily, but it also adds no syntax, format, or edge-case meaning 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 uses a specific verb ('Get') on a clear resource and enumerates the return payload (active framework, membership summary, role, can_write, can_vote_and_comment, writing_instruction). It clearly separates this from list/mutation siblings by describing single-project detail. It does not, however, explicitly name or contrast the sibling hypotize_projects_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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as hypotize_projects_list or hypotize_project_update. The only conditional offered ('when the project has one') concerns a returned field, not invocation.

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 safety is covered. The description adds genuinely useful context beyond that: the returned fields (workspace_id, workspace_name, framework, user_role, can_write, can_vote_and_comment) and what the permission flags mean. It stops short of describing pagination behavior despite the cursor/limit design.

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 clause and the dense field-semantics sentences earn their place given there is no output schema. It is a little heavy in run-on enumeration but contains no filler or redundant restatement of the title.

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

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

For a read-only list tool with annotations covering the safety profile, the description compensates for the absent output schema by enumerating the meaningful returned fields and permission flags. The main gap is that pagination (the limit/cursor mechanism) is never addressed, which an agent needs for exhaustive listings.

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% for the two parameters (limit, cursor), so the description must compensate and does not — neither limit nor cursor is mentioned or explained. The field names it does discuss (framework, user_role, can_write) are response attributes, not input parameters, so they add no input guidance.

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 accessible projects across all workspaces') and immediately scopes it as a cross-workspace listing. It references the sibling hypotize_project_get for field semantics, which helps an agent relate the two, though it does not explicitly frame the singular/plural retrieval distinction.

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-selection guidance is given. The description never tells the agent to prefer this over hypotize_project_get for single-project retrieval or how it relates to other list tools like hypotize_frameworks_list; usage is only inferred from the verb '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 destructive=true, idempotent=true and openWorld=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context by naming the authorization requirement and the concrete INSUFFICIENT_ROLE failure mode with required_roles, which the annotations do not 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?

Two sentences, front-loaded with the purpose and field list, then the role constraint. No filler, though the parenthetical field list is slightly dense and unevenly complete.

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, nested-object mutation with no output schema, the description covers purpose and auth but leaves gaps: idempotency_key semantics, patch merge/patch-vs-replace behavior, and two patch subfields remain unexplained.

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 must carry parameter meaning. It names five updatable fields (name, website, industry, audience, writing language) but omits sub_industry and business_model, and says nothing about how the nested `patch` merges or how idempotency_key should be used.

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 ("Update project context") and enumerates the mutable fields, so the agent knows exactly what the tool touches. It does not, however, distinguish itself from siblings like hypotize_project_create or hypotize_project_delete beyond the verb 'update'.

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 role requirement (editor/owner) implies when the call will succeed, which is useful. But there is no explicit when-to-use versus alternatives guidance, no statement of when-not-to-use, and no direction toward sibling tools such as project_get or project_create.

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?

Beyond the annotations (idempotentHint, readOnlyHint=false), the description adds three pieces of real operational context: create-or-return-existing semantics, the required authorization role, and the exact error code and field returned on failure. That is exactly the kind of auth/behavior disclosure annotations cannot carry.

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 core behavior (create + dedup) is front-loaded ahead of the permission caveat. Every clause carries load-bearing 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 3-param mutation with no output schema, the description covers trigger, dedup semantics, and auth failure behavior, which is most of what an agent needs. It is slightly thin on the return payload and on project_id semantics, but nothing critical 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?

Schema description coverage is 0%, so the description carries the full burden, and it only partially pays it: the uniqueness rule implies tag_name is the dedup key, but project_id and idempotency_key are never explained in meaning or format. An agent can infer retry safety from the text but not what idempotency_key must 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 ("Create a reusable tag") plus a distinguishing behavioral fact (returns the existing tag on duplicate name). It does not name a sibling for contrast, but an agent can readily separate it from hypotize_tags_list on its own.

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 supplies the operative precondition for calling it (editor or owner role) and the consequence of not meeting it (INSUFFICIENT_ROLE with required_roles), which is clear context rather than vague implication. It stops short of explicitly saying "use this instead of hypotize_tags_list when you need a new tag," so no exclusion guidance is present.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description does add one genuinely useful behavioral fact not in the annotations: results are filtered to projects the current user can access, implying permission-scoped output. It says nothing about ordering, pagination, or result shape.

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

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

One sentence, zero filler, with the scope constraint front-loaded. Nothing in it is redundant with the title or 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 simple read-only list tool with one required parameter and no output schema, this is minimally adequate. Because there is no output schema, the description could reasonably say what a tag entry contains or whether results are paginated, and it does not; combined with the 0% schema coverage, a gap remains.

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 for the single parameter. It implies project scoping ('in a project') which maps to the required project_id, but gives no format or source hints for that UUID. Baseline 3 is appropriate when the parameter is self-evident from its name and type.

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 (reusable tags) and scopes them to a project the user can access, which cleanly separates it from hypotize_tag_create and hypotize_projects_list. It does not name a sibling explicitly, so it stops short of a 5.

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

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

No when-to-use, when-not-to-use, or alternative is given. The only contextual hint is that results are limited to a project the user can access, which is a permission constraint rather than usage guidance. An agent must infer why it would call this instead of, say, listing tags indirectly through ideas.

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 destructive=true and idempotent=true, yet the description still adds substantial value: it discloses the atomic priority recalculation, that updated_at changes, the INVALID_DIMENSIONS error behavior for unknown keys, and the required contributor/editor/owner role. These are real behavioral facts not present in structured fields.

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

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

Front-loaded with the core action, followed by side effects and the auth requirement in a compact two-sentence structure. The parenthetical dimension enumeration is dense but earns its place by mapping allowed keys.

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 nested objects and no output schema, the description covers side effects, error behavior, and authorization adequately. Minor gaps remain around idempotency_key and note semantics, but nothing critical 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 0%, so the description must carry the load. It explains the 'dimensions' object well (framework-specific keys, invalid key behavior), but says nothing about 'idempotency_key' or 'note' semantics or constraints, leaving two required parameters 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 (upsert) and resource (the current user's vote in the experiment's framework) with the exact dimension keys for ICE/PIE/RICE and custom frameworks. This is clearly distinguishable from siblings like hypotize_experiment_update or hypotize_experiment_record_outcome.

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 dimension list implies usage context, but there is no explicit when-to-use guidance or naming of alternatives (e.g., how it differs from recording an outcome). The reader must infer when voting is appropriate versus other experiment mutations.

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