TestGraph

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

Beyond the annotations, the description discloses the quorum side effect: two distinct model identities agreeing 'automatically confirm and lock it,' and clarifies that the subject is not moved. This adds meaningful state-change context that readOnlyHint=false and idempotentHint=true do not convey on their own. No contradiction with annotations.

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

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

Three sentences with no filler: the core action, the behavioral mechanism, and the usage guidance each get one sentence in priority order. 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?

The description explains the quorum outcome and lock side effect, which is the main behavioral risk, but with no output schema it leaves gaps: what happens when quorum is not reached, what evidence_fingerprint is for, and what the caller can expect back. Adequate for the core use case, but not fully self-contained for an agent.

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

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

With schema coverage at only 20%, the description must carry parameter meaning. It implicitly clarifies source_model (independent, distinct identity) and evidence (the backing for the agreement), but says nothing about reason or evidence_fingerprint, leaving the least obvious parameter unexplained.

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 ('Submit one independent AI model's evidence-backed agreement with the subject's existing provisional type') and clarifies it is not a reclassification or correction. It distinguishes the intent from siblings like propose_subject_reclassification and correct_subject_fact by anchoring on the existing provisional type and noting the subject is not moved.

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?

Ends with an explicit usage condition: 'Use this when the current type is already correct and no stricter descendant is justified,' which covers both when-to-use and an implied when-not (a stricter descendant is justified). It stops short of a 5 because it never names the alternative sibling tools explicitly, such as propose_subject_reclassification.

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

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

Annotations already establish write behavior, idempotency, and non-destructiveness. The description adds important constraints beyond those: 'Coordinates are WGS84 only and are never silently geocoded,' source provenance is mandatory, and new Places require a canonical key plus durable identifier. This is useful behavioral context without contradicting 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?

Four dense sentences with no filler. The main action is front-loaded, followed by prerequisites and constraints, and every sentence adds 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?

For a complex 11-parameter mutation with no output schema, the description covers prerequisites and key constraints but omits important operational details such as how value/coordinates should be structured, idempotency semantics, and what a successful or failed assertion returns. It is adequate but has clear 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. It clarifies source provenance, new Place canonical_key/identifiers, and WGS84 coordinates, but leaves many parameters unexplained, including value, qualifiers, visibility, valid_from/valid_to, observed_at, and idempotency_key.

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

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

The description clearly states the verb and resource: 'Add a governed location assertion for an existing eligible subject.' This distinguishes it from reading or resolving assertions, though it does not explicitly name a sibling alternative.

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 explicit procedural guidance: 'Resolve the subject and any existing Place first' and specifies requirements for new Places. It does not explicitly state when not to use this tool or name alternatives, so it stops short of a 5.

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

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

Beyond the idempotentHint annotation, the description adds concrete behavioral detail: atomic claiming, safe repetition, the DELIBERATION_ALREADY_CLAIMED error condition, and the scope limitation that claiming grants no authority beyond the stored deliberation. This meaningfully enriches what annotations alone 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?

Three sentences with no filler. The core action is front-loaded, and the second and third sentences add important behavioral caveats. 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?

The description covers claim semantics and conflict behavior well, and annotations handle idempotency and safety. However, with no output schema and no parameter-level explanation, an agent still lacks clarity about expected return values and the optional source_model field.

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. It does not explain deliberation_id, idempotency_key construction, or the optional source_model parameter. The 'repeating the same claim is safe' sentence hints at idempotency_key semantics, but the mapping is implicit rather than explicit.

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 ('claim'), names the resource ('open deliberation'), and identifies the actor ('authenticated MCP client'). It also conveys atomicity, which distinguishes this from sibling create/get/list tools even without naming 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?

The description clearly implies when to use the tool: when you want to claim an open deliberation. However, it gives no explicit guidance about alternatives, exclusions, or prerequisite steps such as listing open deliberations first.

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

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

Annotations already indicate destructive and idempotent behavior; the description adds valuable context by specifying the compare-and-swap precondition, mandatory evidence and reason, and the immutable correction record in subject provenance. This goes beyond the annotations without contradicting them.

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 dense sentences carry the action, preconditions, side effects, and alternative routing. There is no filler or repetition of schema content.

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

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

The description gives strong high-level context for a destructive, idempotent correction operation, but with eight required parameters and no output schema, the missing parameter-level guidance leaves meaningful gaps. It is adequate for choosing the tool, less so for constructing a fully correct call without additional 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 only 13%, so the description must compensate for eight required parameters. It clarifies expected_value and emphasizes evidence_sources/reason, but leaves subject_id, field_root, field_path, corrected_value, and especially idempotency_key with little or no added meaning. The agent gets structure but not semantics for most 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 opens with a precise verb and object: 'Replace one incorrect identifier or attribute using the stable subject ID.' It also differentiates itself from enrich_subject by stating that this tool corrects existing facts rather than adding missing ones.

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 explicitly routed: 'Use enrich_subject for missing facts; never use this operation merely to add a value.' It also states the precondition that the current value must match expected_value, giving the agent a clear gate for when invocation is appropriate.

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

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

Annotations already indicate this is not read-only, so the description adds valuable non-obvious context: content is advisory and not authority, the deliberation is private and user-owned, and governance proposals remain inactive until explicit user approval. This helps prevent misuse beyond what the structured annotations convey. It does not detail output or auth requirements, but the annotations cover the basic safety profile.

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

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

The description is front-loaded with the core purpose, then provides a conditional governance recipe, then closes with a safety caveat. Every sentence earns its place and there is no filler or repetition. It is appropriately sized for an 8-parameter tool with a nested context object.

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

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

Given the complex governance workflow, no output schema, and sparse schema descriptions, the description is largely complete for correct invocation: it explains what to create, how to key it, how to express an induction-guidance proposal, and what behavioral constraints apply. It stops short of describing return values, error behavior, or the exact semantics of constraints and acceptance_criteria, but these are minor gaps relative to the strong guidance provided.

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 low, and the description compensates by explaining the purpose of canonical_key and by giving a precise recipe for the nested context object, including context.target_model. It clarifies a non-obvious distinction between top-level target_model and context.target_model. Some optional parameters like constraints and acceptance_criteria remain inferred from their names, but the most critical parameters are meaningfully 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?

The description uses a specific verb and resource: it creates a private, user-owned question for multiple authenticated MCP clients. This clearly differentiates it from retrieval siblings like get_deliberation and list_open_deliberations. The opening sentence makes the tool's job unmistakable.

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

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

The description gives explicit when-to-use guidance for the induction-guidance variant, including the exact context fields and the inactive-until-approval behavior. It also tells the agent to use a stable canonical_key for later retrieval. However, it does not explicitly name alternatives or state when not to create a deliberation beyond that variant.

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

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

The description adds substantial behavior beyond the annotations (destructiveHint=true, idempotentHint=true): server-side ownership enforcement, cascade deletion of dependent AI assessments, the precise conditional rule for subject deletion (same creator, no remaining reviews, no subject relationships), and confirmation protocol. It also reinforces the idempotentHint with the 'do not ask for a second confirmation' instruction. All behavior is consistent with annotations — a destructive, idempotent mutation.

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

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

Four sentences, each earning its place: the core action, ownership guarantee, cascade/conditional side effect, and an agent-facing behavioral rule. The action is front-loaded in the first sentence. It is slightly dense — the subject-deletion clause packs three conditions into one long sentence — and the confirmation theme appears twice, creating minor 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 destructive tool with no output schema and zero param coverage, the description covers the critical invocation semantics: what is deleted, what cascades, what is preserved, who may delete, and when confirmation is needed. Gaps remain — the return value/error behavior for a non-existent review and the explicit semantics of idempotency_key — but these are secondary to the full disclosure of the operation's effects, which is excellent.

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?

Given 0% schema description coverage, the description carries the full burden and largely delivers: 'one review' maps to id, 'explicitly requests deletion' maps to confirm_deletion, and the entire subject-preservation condition explains the behavior of delete_orphan_subject. The only parameter left implicit is idempotency_key, whose purpose is only hinted at by the idempotentHint annotation and the no-double-confirmation note. Strong compensation, but not systematic per-parameter documentation.

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

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

The description opens with a specific verb and resource — "Permanently delete one review" — and the title reinforces the scope ("Delete a user-owned review"). Ownership, single-review scope, and permanent nature are all explicit, leaving no ambiguity about what this tool does. The only sibling that could compete is save_experience, and the destructive framing clearly distinguishes this from any create/update operation.

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 a clear precondition: use only "after the authenticated user explicitly requests deletion," and a clear when-not instruction: "Do not ask for a second confirmation when the current user request already explicitly authorises deletion." No alternative tools are named, but no sibling performs deletion, so exclusions are unnecessary. Clear context with no explicit alternatives.

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

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

The description adds substantial operational detail beyond annotations: it explains deterministic idempotency keys for safe retries, preserves existing conflicting values, batches concurrent writes up to 10, and reveals that a successful response includes durable workflow state with a next_action tool to call. These details are not present in the annotations and meaningfully shape agent behavior.

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

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

The description is long and dense, but it is front-loaded with the core purpose and then structured into usage, behavior, collection handling, and workflow sections. Every sentence contributes a rule or constraint, though some repetition occurs (e.g., 'do not omit members'), making it slightly less concise than ideal.

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

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

Given the tool's complexity, no output schema, and rich nested parameters, the description is remarkably complete. It covers the full lifecycle: what to enrich, how to handle identity and provenance, collection discovery with source manifests, idempotency and concurrency, and the post-enrichment workflow involving next_action. An agent has enough guidance to invoke the tool correctly in most scenarios.

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

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

With schema description coverage around 40%, the description compensates by giving meaning to key parameters: idempotency_key via deterministic key derivation, canonical_key via reuse guidance, retrieval_uses via required reasons and likely query examples, and source_manifest via exhaustive source-surface mapping. It does not individually document every parameter, but the operational instructions clarify the most important ones.

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

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

The description opens with a specific verb and resource: 'Add missing identifiers, attributes, provenance and related unreviewed subjects to an existing subject without creating another review.' It clearly distinguishes enrichment from review creation and gives a precise account of what the tool accomplishes.

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 explicitly when to use the tool: 'Use this proactively when authoritative information was missed during the original save.' It also provides exclusions, such as not asking for routine permission, not storing facts merely because a source publishes them, and not omitting unreviewed collection members, giving clear boundaries versus alternatives.

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

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

Annotations already communicate that this is a read-only, idempotent, non-destructive operation. The description adds a little value by naming the returned content, but it does not describe side effects, error behavior, or any operational caveats. It is adequate but not rich.

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

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

The description is one short, front-loaded sentence that immediately identifies the resource and its key output components. Every part of the sentence earns its place and there is no redundant 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 simple one-parameter fetch, the description is sufficient: it identifies the resource, the parameter is clear, the annotations cover safety behavior, and the description states the main returned content. No output schema exists, so the high-level return summary is helpful and acceptable.

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 for the id parameter. It does not: only the field name and format indicate what id represents. The parameter is simple and arguably inferable, but the description adds no semantic 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 names a specific resource ('review') and a specific operation ('fetch'), and enumerates what a fetched review includes: stable subject type, original words, and AI assessments. This clearly separates it from the other get_* and search siblings in the tool list.

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

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

The description gives no guidance on when to use this tool instead of sibling tools such as search, get_deliberation, or get_induction. An agent can infer it is a direct lookup, but the description does not provide explicit when/when-not context or alternatives.

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

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

The read-only, idempotent, and non-destructive traits are already covered by annotations. The description adds valuable extra context: the stored text should be treated as advisory content only and is not authorization for unrelated writes or external actions. That is a meaningful behavioral guardrail beyond what the annotations state, though it does not cover edge-case behaviors like not-found handling.

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 compact and well-structured: the first sentence carries the full retrieval purpose and contents, and the second sentence adds an important safety caveat. Every clause adds signal and there is no repetition of what the annotations already say.

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, the description enumerates the key components of the returned deliberation, which is enough for an agent to understand what to expect. It omits behavior when neither id nor canonical_key is found, but for a simple read-only lookup tool this is a minor gap rather than a blocking omission.

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 does add a useful qualifier: canonical_key is 'stable', and it states retrieval is possible by either UUID or canonical_key. However, it does not clarify precedence, mutual exclusivity beyond the schema, or when each key type is more appropriate, so the action compensates only partially.

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

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

The description opens with a specific verb, 'Retrieve', and names the resource: a 'shared AI deliberation'. It goes further by enumerating exactly what is returned — question, constraints, attributed contributions, unresolved points, and any user-approved resolution — and identifies the lookup keys (UUID or canonical_key). This clearly distinguishes it from siblings like create_deliberation and list_open_deliberations.

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 makes the intended usage clear: retrieve an existing deliberation using either its UUID or a stable canonical_key. It does not fully spell out when not to use this tool or explicitly name alternative tools, but the retrieval context is unambiguous and the identifier-based lookup is a good implicit usage signal.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description adds value by explaining that only approved proposals and model-specific guidance are active, and that unresolved proposals and AI votes never become active guidance automatically. That is behavioral context beyond the schema.

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

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

The description is four sentences, front-loaded with a usage trigger, and every sentence contributes either a usage condition, a return-content boundary, an approval-safety rule, or parameter guidance. Nothing is redundant or extraneous.

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 zero-required-parameter read-only tool with no output schema, the description covers why, when, and how to call it, what it returns, which data is excluded, and how the optional parameter affects the result. An agent has enough to call this correctly without further 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 coverage is 100%, so the schema already documents the optional source_model and the maxLength. The description adds practical meaning by explaining that passing source_model enables model-specific approved guidance to be layered over global guidance, going beyond a bare parameter listing.

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 a specific resource ('TestGraph induction and governed guidance'), and clarifies what it returns: server baseline plus user-approved global and model-specific guidance. It is distinct from sibling tools because it focuses on induction/orientation guidance rather than assertions, deliberations, or contributions.

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

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

The description gives explicit call conditions: first use of TestGraph, after an MCP refresh, or whenever current shared operating guidance is needed. It does not explicitly name alternative tools or state when not to use it, but the triggering contexts are clear enough that an agent can select this tool confidently.

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

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

Annotations already establish that this is a safe read-only, idempotent operation, so the bar is lower. The description adds some behavioral context by saying 'all visible' and outlining the returned data areas, but it does not disclose behavior such as pagination, limits, or how 'visible' is determined.

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

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

The description is a single focused sentence with no filler. It front-loads the main purpose and uses lists to efficiently convey the return content.

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

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

The one-parameter getter is simple, and the annotations cover the safety profile, so a short description is acceptable. However, the description omits useful context such as pagination or output structure, and the term 'visible' is left undefined, leaving some uncertainty about the full semantics of the 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?

With 0% schema description coverage, the description must clarify the parameter, but it only refers to 'one subject' without naming subject_id or explaining its role beyond the obvious property name. It adds minimal value beyond the input 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 ('Return') and identifies the exact resource: all visible location assertions for one subject. It also lists included content (provenance, conflict state, Place identity, migration drift), which clearly separates it from sibling tools like get_deliberation or resolve_location_assertion.

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 what the tool does but gives no explicit guidance on when to use it versus alternatives, no exclusions, and no mention of alternative tools. An agent must infer that it is the query tool for location assertions rather than being told.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, lowering the bar. The description adds useful context by specifying that the returned version is 'exact' and 'live', and by naming build_sha and deployment_id as the fields to compare against the public /version endpoint. There is no contradiction with annotations.

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

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

Three sentences deliver the purpose, usage conditions, and troubleshooting guidance without any filler. The core function is front-loaded, and every sentence contributes meaningful 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?

Despite having no output schema, the description names the key returned fields and explains how to use them. Given the tool's zero-parameter simplicity and the strong annotations, an agent has everything needed to decide whether and how to call it.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. The description instead adds value by indicating what the response will contain, which is more relevant for a parameterless tool.

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 ('Return') and a specific resource ('exact TestGraph MCP server version and live deployment identity'), clearly framing the tool as a diagnostics operation. This is distinct from the domain-focused sibling tools and leaves no ambiguity about what the tool does.

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

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

The description explicitly names when to use the tool: checking a stale connection, endpoint mismatch, or deployment issue. It also provides an exclusion ('ordinary writes do not require a preceding version probe'), which gives an agent clear decision guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it returns not only the classification state but also the decision audit, and it warns that confirmed classifications are locked against routine reassessment.

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

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

The description is two short sentences with no filler. The primary verb and resource are front-loaded, and the policy warning is presented distinctly after the functional description.

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-parameter read operation with rich annotations, the description covers the essential information: what is returned (state and audit) and a key policy constraint (locked confirmed classifications). It does not detail error or not-found behavior, but that is a minor gap given the simplicity of the tool.

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

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

The schema contains a single subject_id parameter with 0% description coverage, and the description does not mention the parameter at all. The parameter name is somewhat self-explanatory, but the description adds no semantic guidance about what subject_id refers to or how it relates to the classification state.

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 ('Read') and specific resources ('current classification state' and 'decision audit'), making the tool's purpose immediately clear. It also differentiates from siblings like propose_subject_reclassification and reopen_subject_classification by noting that confirmed classifications are locked and not routinely reassessed.

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 clearly indicates when to use this tool: when you need the current settled classification state and its audit trail. It also provides an implicit exclusion by warning that confirmed classifications must not be routinely reassessed, though it does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: results are scoped to the authenticated user, structured, redacted, and limited to metadata/summaries rather than raw content. This goes beyond what annotations 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 compact sentences with no filler. The first sentence states the action and object clearly; the second sentence clarifies content boundaries. 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?

No output schema exists, but the description adequately tells the agent what will be returned (tool/outcome/workflow metadata and redacted summaries). It does not explain pagination, ordering, or limit behavior, but for a simple one-parameter list tool this is not a critical 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 does not mention the 'limit' parameter. While the parameter name and schema constraints (default 50, min 1, max 200) make its purpose inferable, the description provides no explicit semantics about how limit controls the returned telemetry.

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 ('List') and a precise resource ('authenticated user's structured, redacted MCP interaction telemetry'). It also states exclusions ('not raw conversations or secrets'), which distinguishes it from sibling tools like list_my_workflows or list_open_deliberations.

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 explicit when-to-use guidance or alternatives are provided. The only exclusion ('not raw conversations or secrets') describes content boundaries, not decision criteria for when this tool should be selected over siblings. The agent is left to infer usage context from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful scoping (server-owned, durable, authenticated user) but does not disclose behavior such as ordering, pagination, or what the returned items look like; this is consistent with the calibration example where read annotations plus scoping but no output behavior earns a 3.

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 verb and resource are front-loaded and the usage hint follows immediately. Every clause contributes information.

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

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

For a simple read-only list tool with one optional parameter and safety covered by annotations, the description gives enough context to select and invoke it: user scope, content categories, and an explicit use case. The lack of any mention of return shape or pagination keeps it from a 5, but it is not a material gap for this low-complexity tool.

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

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

There is one optional 'limit' parameter and the schema fully constrains it with default, minimum, and maximum, but schema_description_coverage is 0% and the description does not mention the parameter at all. Because the description must compensate when coverage is low and it does not, the parameter semantics score is 2.

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 ('List'), a resource ('durable server-owned workflow state'), and a user scope ('authenticated TestGraph user'), plus concrete content categories. It does not explicitly differentiate itself from siblings such as list_open_deliberations or list_my_mcp_interactions, so it falls just short of 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?

'Use this to inspect pending second-model work, disputes and completed procedures' gives a clear context for when to call the tool. No alternatives or when-not-to-use guidance is provided, so 4 rather than 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 readOnlyHint, idempotentHint, and destructiveHint false, so the description needs only add value beyond those. It adds useful scoping ('this user's' open work) and alias semantics, but it does not disclose return format, pagination, or ordering behavior. This is acceptable but not rich.

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

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

Three tight sentences each add something: scope and purpose, practical filter guidance, and alias clarification. There is no filler, repetition, or boilerplate.

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 listing tool with zero required parameters, the description is sufficiently self-contained: it explains who the result belongs to, why to use it, how to filter, and how it relates to claiming. No output schema exists, and the basic list contract is clear from the title and first sentence.

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 only 33%, but the description compensates for target_model and unclaimed_only by linking them to concrete work-discovery workflow: 'find work addressed to a model label' and 'before claiming a task'. It also reinforces the gpt/chatgpt aliases. The limit parameter is adequately explained by its schema constraints and name.

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 identifies a specific verb and resource: listing this user's open deliberations. It also explains the purpose — allowing an authenticated AI to discover work without being handed a UUID or canonical key — which clearly distinguishes it from sibling tools like get_deliberation and create_deliberation.

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 concrete usage context: use it for discovery without identifiers, and use target_model plus unclaimed_only to filter before claiming a task. It does not explicitly name sibling alternatives or say when not to use it, but the intended workflow is clear and actionable.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond those annotations: it returns stable experience IDs alongside 1-based positions, and it explicitly warns that positions are display-only and must never be used in later mutations. This clarifies important response semantics.

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 written sentences: the first states the core behavior and return values, and the second adds an important usage constraint. There is no filler or repetition of schema or annotation content.

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

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

For a simple, single-parameter, read-only list tool with safety annotations, the description covers the essential context: scope, filtering, return contents, and the critical rule that positions are not valid mutation references. Pagination and ordering are not mentioned, but they are not necessary for an agent to invoke this tool 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?

The only parameter, visibility, is fully defined by its enum in the input schema, and the description maps to it with 'in one visibility state.' However, schema description coverage is 0%, and the description does not explain what each enum value (especially aggregate_only) means or how to choose among them. The schema carries most of the semantic weight here.

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 ('List'), a specific resource ('the authenticated user's reviews'), and a clear filtering scope ('in one visibility state'). It also states what the tool returns (stable experience IDs plus 1-based positions), which distinguishes it from sibling tools like set_review_visibility (a mutation) and list_open_deliberations (a different resource type).

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 clearly implies when to use the tool: when you need a read-only list of the current user's reviews filtered by visibility. However, it does not explicitly mention alternatives or when not to use it, such as distinguishing it from set_review_visibility or other listing/search 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?

The description goes well beyond annotations by disclosing the candidate/confirmation/lock lifecycle, the two-distinct-model agreement requirement, and the server-side validation that client guidance cannot bypass. These are behavioral details not available in 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 core purpose and lifecycle are front-loaded, and the additional classification-vocabulary guidance is relevant for constructing a valid target_subject_type and reason. It is somewhat long, but each sentence contributes operational or domain context for a complex 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?

The description covers the core lifecycle, locking behavior, and validation constraints, which is strong for a non-read-only operation. However, it omits explicit return/response semantics and some parameter-level details, and no output schema exists to fill that gap.

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

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

Schema coverage is only 17% (only source_model is documented in the schema), and the description does not explain individual parameters such as evidence_fingerprint, target_subject_type, evidence, or reason. It gives domain background for subject-type naming but does not compensate for the low parameter coverage.

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 operation: submitting one model's evidence-backed refinement to a strict descendant type. The title and description distinguish it from other classification tools by emphasizing the proposal/lock lifecycle rather than merely reading or affirming classifications.

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

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

Provides clear context for when to use the tool: for a single independent model's candidate refinement to a more precise type, with the two-model agreement rule. It includes a when-not (locked subjects are not reopened by later opinions) and broad guidance about semantic heads, though it does not explicitly name sibling tools as alternatives.

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

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

Beyond annotations, the description discloses important behavioral traits: it 'does not infer consensus,' it records accepted contributions and remaining disagreement, and a successful user-approved resolution becomes active guidance returned by get_induction. It also warns that AI votes alone cannot activate guidance, which is non-obvious and valuable context.

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

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

The description is three sentences long, front-loads the core action, and every sentence adds a distinct piece of information: what the tool does, what it does not infer, and what downstream effect a successful resolution has. There is no filler or repetition.

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

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

For a 7-parameter tool with no output schema, the description provides the essential behavioral context: the requirement for user_approved=true, the distinction from consensus, and the side effect on get_induction. It leaves some details implicit, such as what happens when user_approved=false and the exact use of idempotency_key, but the annotations cover idempotence and the core decision criteria are clear.

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 are no parameter descriptions in the input schema (0% schema coverage), so the description must compensate. It does add meaning for user_approved, accepted_contribution_ids, and unresolved_points by matching 'requires user_approved=true' and 'records accepted contributions and remaining disagreement.' However, other parameters like idempotency_key, rationale, and resolution are not given semantic clarification in the description.

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

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

The description opens with a specific verb and resource: 'Close a deliberation with the user's explicit decision.' It also clarifies the precise nature of the operation by stating it records accepted contributions and remaining disagreement rather than inferring consensus, and it distinguishes its effect from AI voting authority, which clearly separates it from sibling deliberation tools.

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 clear context for when to use this tool: after the user has made an explicit decision and when user_approved=true. It also states a key when-not condition: AI votes alone have no activation authority. It does not explicitly name alternative tools to use instead, but the conditions are concrete enough for an agent to route correctly.

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

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

Annotations already cover idempotency and non-destructiveness, so the bar is lower. The description adds valuable behavioral context by explaining that existing canonical fields are attached automatically on first use and that explicit pre-attachment to subject types is allowed. It does not cover error behavior or permissions, but the added context 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?

Three sentences, front-loaded with the core purpose, followed by a usage guardrail and a preference rule. Every sentence earns its place, and there is no filler or redundant wording.

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

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

Despite strong usage guidance, the description omits all parameter semantics for a 5-parameter tool with a nested json_schema object and no output schema. An agent cannot reliably construct a valid call, especially the json_schema parameter, without additional information.

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 compensate but only gestures at subject_types and canonical_name through phrases like 'globally canonical field' and 'pre-attach to subject types.' The required json_schema remains completely unexplained, and aliases/description are never mentioned, so an agent must guess how to construct the payload.

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 action ('Register') on a specific resource ('a genuinely new globally canonical field') and contrasts it with pre-attaching to subject types. This distinguishes it clearly from siblings like register_subject_type_alias and makes the tool's scope unambiguous.

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

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

Explicitly says not to ask routine confirmation for existing canonical fields because valid existing fields attach automatically on first use, and tells users to prefer raw_text for one-off narrative detail. This provides clear when-to-use and 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 cover idempotency and non-destructiveness. The description adds meaningful behavioral context: registering an alias does not require another AI to prefer the same name, and wording disagreement alone is not a semantic conflict. This goes beyond the structured annotations without contradicting them.

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 compact and front-loads the core purpose. The cautionary sentences are relevant, though 'Never use this to express a category relationship' and 'Use this for genuine naming equivalence' are slightly redundant.

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

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

For a simple two-string registration operation with an idempotent annotation, the description adequately covers what the tool does and the key semantic constraint. It does not describe return values or duplicate-alias behavior, but no output schema exists and annotations cover the safety profile.

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 partially compensates by defining subject_type as an 'existing stable subject type' and alias as a 'genuinely equivalent expression.' However, it lacks operational specifics such as whether subject_type must be a resolved id, whether aliases must be unique, or what happens on duplicate registration.

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-resource pair: 'Map a genuinely equivalent expression to an existing stable subject type.' It clearly distinguishes the operation from category-relationship tools, so an agent can tell it apart from siblings like set_type_relationship.

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 explicit guidance: use for genuine naming equivalence, never for category relationships. It does not name a specific sibling alternative, but the boundary is clear enough for routing.

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

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

Annotations already establish that the tool is not read-only and not destructive, and the description adds meaningful behavioral context: it acts only on confirmed classifications, requires one of four valid triggers, and explicitly rejects ordinary disagreement as a reason. This goes beyond what the annotations or schema alone communicate.

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 concise sentences with no filler. The main operation is front-loaded, the allowed triggers are enumerated compactly, and the exclusion rule is stated in one clear sentence.

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 is strong for deciding when to call the tool but weak for actually invoking it correctly. With five parameters, no parameter descriptions, and no output schema, an agent still lacks guidance on what evidence should contain, what user_approved means, and what happens after reopening.

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 needed to explain the parameters, but it only indirectly maps trigger values to the allowed reasons. It does not clarify the meaning or expected shape of reason, evidence, or user_approved, leaving several required parameters underspecified.

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 ('Reopen') and resource ('confirmed/locked subject classification'), and narrows the operation to four explicit trigger categories. This clearly distinguishes the tool from siblings like propose_subject_reclassification or affirm_subject_classification by focusing on an already-confirmed state.

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

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

The description gives explicit when-to-use criteria ('only for a user correction, contradictory new evidence, a retired type, or vocabulary invalidation') and a strong when-not-to-use rule ('Ordinary later disagreement never reopens it'). It does not name sibling alternatives, so the guidance is slightly incomplete on routing, but the inclusion and exclusion conditions are very 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 mark the operation as non-read-only, non-destructive, and idempotent. The description adds meaningful behavioral context by explaining that the submitting client cannot resolve its own contested claim without explicit user approval, which clarifies the approval requirement beyond the schema's user_approved default.

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 concise sentences with no filler. The core action is front-loaded, and the added approval constraint 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 mutating tool with no output schema and zero parameter coverage, the description is too thin. It captures the approval prerequisite but does not explain the workflow around contested assertions, the role of idempotency, or how a caller should obtain the assertion_id and what happens after resolution.

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. It only indirectly explains 'decision' ('accept or reject') and hints at 'user_approved' (explicit user approval), but it does not add meaning for assertion_id, rationale, or idempotency_key, leaving most parameters semantically under-specified.

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 action ('Accept or reject') on a specific resource ('a contested location assertion'), and the title reinforces it. It is clear enough to distinguish from most siblings, though it does not explicitly differentiate from similar resolution tools like record_resolution.

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

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

The description implies when to use the tool: when a location assertion is contested and the submitting client needs explicit user approval to resolve it. However, it does not state when not to use it or name alternative tools, leaving some selection ambiguity against siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the read-only safety profile. The description adds that reviewed and unreviewed subjects are both included and emphasizes reuse over duplicate creation, but it stays close to the annotation-provided read-only semantics and doesn't address other consequences like empty results.

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

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

The description is concise and front-loaded with the most important use case. Every sentence contributes, though 'before declaring a new one' and 'instead of creating a duplicate' repeat the same core idea, which prevents a perfect conciseness score.

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?

This is a straightforward look-up tool and the description explains its purpose and when to call it, which is good. However, there is no output schema, and the description does not mention what happens when no match is found or which identifier returns enough results. It is adequate, but there are clear 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?

With 0% schema description coverage, the description carries heavy weight here. It usefully maps many parameters (stable type, canonical key, name, authoritative identifier value), but it leaves identifier_key and limit undocumented and does not clarify which combination of parameters should be supplied. Partial compensation for the schema gap, 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?

The description clearly states the tool resolves/looks up an existing subject instead of creating a new one, which is a concrete verb and resource. It also distinguishes this tool from declaring/creating a subject, so an agent immediately knows its role.

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

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

The description explicitly tells the agent when to use this tool: before adding a collection subject, so an existing subject_id and canonical_key can be reused instead of creating a duplicate. It lacks explicit when-not-to-use instructions or named alternatives, but the intended use case 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?

Beyond the annotations, the description discloses important behavior: existing dictionary entries are reused, only missing provisional nodes are created, belongs_to relationships are added, cycles are rejected, and the server independently validates structural writes. This goes well beyond what annotations or the schema could 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?

Although the description is long, it is dense with decision-relevant guidance for a nuanced classification task. The most important operational instructions are front-loaded, and each subsequent sentence addresses a distinct semantic rule without unnecessary repetition.

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

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

Given the single parameter, the absence of an output schema, and the conceptual complexity of subject hierarchy resolution, the description covers preconditions, input semantics, server behavior, rejection rules, and client-side validation limits. An agent has enough information to call the tool 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?

The only parameter, terms, is richly explained despite zero schema description coverage. The description specifies ordering (broad-to-specific), gives an example, and adds extensive semantic guidance about what counts as a distinct concept, how to handle modifiers, and why naming variants should reuse identity.

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

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

The description clearly states the tool's purpose and trigger condition: use it after vocabulary_index when a specific subject type does not yet exist. It specifies the exact input format (broad-to-specific terms) and what the server does with them, making it easy to distinguish from related resolution tools.

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 strong usage context, including when to use the tool, what to exclude ('review'), and how to handle naming variants. However, it does not explicitly name a fallback alternative tool when the subject type already exists, so the full vs-alternatives guidance is implied rather than explicit.

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

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

The description discloses meaningful input normalization behavior beyond the read-only and idempotent annotations, including case, punctuation, possessives, and ordinary plurals. It also clarifies that the returned stable subject-type ID is the authoritative identity boundary, which helps shape the caller's expectations about ambiguity and equivalence. There is no contradiction with the readOnlyHint, idempotentHint, or destructiveHint annotations.

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

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

The description is three tightly written sentences, each adding distinct information: purpose, normalization behavior, and alias acceptance. It front-loads the core action and avoids filler or redundancy. Everything included helps an agent choose and invoke the tool correctly.

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-parameter, read-only, idempotent lookup tool, the description is largely complete: it states what input is accepted, how it is processed, and what output is returned. It does not describe behavior for unmatched or unresolvable terms or the exact response format, but this gap is minor given both the absence of an output schema and the tool's simple contract.

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 schema description coverage at 0%, the description provides nearly all meaningful semantics for the single 'term' parameter: it is flexible, normalized for certain linguistic variations, and accepts aliases. It does not make an explicit named mapping to the parameter or provide concrete examples, but since there is only one parameter, an agent can reliably infer how 'term' should be supplied.

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

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

The description opens with a specific verb and resource pair: "Resolve flexible input to one stable subject-type ID." This clearly names the operation, the input, and the output, making it distinguishable from adjacent tools like resolve_subject or resolve_subject_hierarchy. The added phrases about input normalization and stable IDs strengthen the purpose statement without ambiguity.

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 clear usage context by stating that aliases are valid lookup inputs and that canonical wording is not required. This tells an agent when to use the tool: when facing flexible, non-canonical, or alias-laden input. It does not explicitly name alternatives or negative conditions, so it stops short of the highest score.

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 mark the operation destructive and idempotent. The description adds meaningful behavioral context beyond annotations: the retired edge persists as a rejection tombstone to prevent silent recreation, and the operation preserves subject type, subjects, and reviews. No contradiction with annotations exists.

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 redundancy. The primary action and key preservation guarantee come first, and the tombstone side effect earns its place as crucial behavioral information. Every phrase adds 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 a destructive tool, the description covers the purpose, preservation scope, and the notable tombstone behavior. However, it omits how to map the required fields, what counts as a valid exact relationship, and what a successful retirement returns. With no output schema and minimal parameter guidance, the description is adequate but leaves noticeable 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%, yet the description adds no explanation of source_type, target_type, relationship, or reason beyond their names. The phrase 'exact semantic relationship' hints at the relationship parameter, but it does not clarify what values are valid or how the required parameters combine. The description fails to compensate for the schema's lack of field documentation.

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 precise verb and resource: 'retire one exact semantic relationship.' It also distinguishes the behavior from related operations by specifying what is preserved (subject type, subjects, reviews) and the rejection-tombstone side effect. The title 'Retire an incorrect subject classification' adds context, and the description differentiates it from siblings like set_type_relationship.

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

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

The description implies the use case: removing an incorrect semantic relationship while keeping the underlying subject intact. It does not explicitly name alternatives or state when not to use it, so an agent must infer selection criteria from sibling names and the tombstone effect. This is adequate but not explicit 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?

The description adds meaningful behavioral detail beyond the annotations by explaining how idempotency keys should be derived, why concurrent writes should be batched in groups of up to 10, and that retries should return existing writes. This supplements the idempotentHint annotation with actionable, non-obvious behavior.

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

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

The description is dense but efficient, with a clear front-loaded purpose and two additional sentences that each add non-redundant operational guidance. The phrasing is somewhat complex, but every sentence earns its place.

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

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

For a tool with 8 parameters, zero schema description coverage, no output schema, and a large sibling set, the description is incomplete. It covers concurrency and idempotency well, but omits parameter semantics, return behavior, and any guidance distinguishing this tool from alternatives, leaving agents to guess at core 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%, so the description is the only place for parameter meaning, but it does not explain most parameters such as experience_id, assessment_type, analysis, evidence, conclusion, confidence, or source_model. It only obliquely references idempotency_key derivation, leaving required and optional parameters largely undefined.

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

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

The description clearly states a specific verb ('Save'), a specific resource ('separately attributed AI analysis'), and the target ('against the exact review it evaluates'). This makes the tool's core function clear, though it does not explicitly name sibling tools or contrast itself with save_experience or submit_contribution.

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

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

The description provides operational guidance about batching concurrent writes and idempotency, but it does not explain when to use this tool versus alternatives. No sibling tool is mentioned, and there is no condition or exclusion that would help an agent decide between save_assessment and similar 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?

Beyond the idempotentHint annotation, the description reveals substantial server-side behavior: manifests are stored and verified, collection_id and manifest_revision are reused, idempotency keys prevent duplicates, independent writes can be batched up to 10, and routine retries should happen without asking the user. It also discloses defaults such as experience date and warns against inventing facts or silently geocoding coordinates.

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 extremely long and contains repeated concepts, such as the shared-graph enrichment rationale appearing more than once, and it presents everything as one dense paragraph without bullets or clear sectioning. The volume is partly justified by the tool's genuine complexity, but the repetition and lack of structure keep it from being concise.

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 17 parameters, nested objects, no output schema, and deep server-side semantics, the description is remarkably complete: it covers idempotency, concurrency, manifest refresh, coverage statuses, collection traversal evidence, retry policy, and ask-vs-act boundaries. An agent has enough context to invoke the tool correctly in most realistic scenarios.

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

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

Schema description coverage is only 18%, so the description carries heavy responsibility for explaining parameters, and it largely delivers. It explains subject_enrichment_check statuses, applied_fields/retrieval_uses provenance requirements, collection_assessment mandates, canonical identifier storage, structured_data preservation, and idempotency key derivation. Some parameters like visibility and subject_provenance receive no semantic guidance, but the most complex and error-prone fields are well covered.

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

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

The description opens with a specific verb and resource: 'Save a review against an already-resolved stable subject type,' which clearly states the core operation. It does not explicitly name or contrast sibling tools such as enrich_subject or save_assessment, so it misses the highest bar for sibling differentiation, but the core purpose is unambiguous.

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

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

The description gives detailed workflow context: when to retry automatically, when to ask the user, when to use unavailable, not_applicable, and ambiguous, and when to reuse collection_id versus resubmit a manifest. It does not explicitly state 'use X instead of this tool' for any sibling, but the usage context is strong and actionable.

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 indicate read-only and idempotent behavior, and the description adds meaningful characteristics: lexical matching, soft alias handling, coverage-based completeness, no merging by display name, and the fact that a search miss does not prove absence. This helps an agent interpret results appropriately and matches the annotation set.

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

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

The description is dense and front-loaded, with the core purpose and main constraints stated early. Some repetition occurs, especially around lexical searching and one-keyword-at-a-time guidance, but the additional context is genuinely useful for safe use.

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

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

Given no output schema, the description explains the essential return semantics: reviewed vs unreviewed subjects, subject_id/subject_type identity, cursor-based exhaustive retrieval, collection_coverage, and coverage_status=complete as the only basis for claiming absence. It gives an agent all context needed to perform the operation without overclaiming.

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 the cursor parameter has schema-level description coverage; the tool description compensates partially by explaining query behavior, subject_type-only fallback, pagination, and coverage-related result semantics. But limit and include_related are not mapped to their usage meaning, leaving two parameters under-specified for an agent despite the long textual descriptions.

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

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

The description opens with 'Search reviews plus matching reviewed or unreviewed subjects,' immediately naming the verb, resource, and scope. It further differentiates this tool from siblings by stating it is lexical rather than semantic and by emphasizing that identity is based on subject_id/subject_type rather than display names.

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 explicit workflow instructions: try one keyword at a time, follow up with exact subject-name searches, paginate using cursor until complete, and fetch each returned review before answering. It also provides when-not-to-stop guidance for location queries and says partial or unknown coverage must be reported as uncertainty, which is strong usage 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 non-read-only, idempotent, non-destructive behavior. The description adds meaningful context: only authenticated-user-owned reviews can be changed, stable IDs are required, and setting public also forces publication_status=published. It does not explain side effects for the other visibility values, but it goes well beyond the structured annotations.

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

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

Three tightly written sentences with no wasted words. The core action comes first, followed by the practical ID-resolution workflow and then the non-obvious publication side effect. Everything present adds 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 a mutating tool with no output schema, the description covers the essential invocation context: the resource scope, the auth constraint, the source of the ID, and a non-obvious side effect. The main gaps are the meanings of unlisted and aggregate_only, and what happens to publication_status when moving away from public, but these are not blocking for correct tool selection.

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

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

With 0% schema description coverage, the description must explain parameters itself. It does clarify that experience_id is a stable identifier and explains how to obtain it from list_reviews_by_visibility. It also adds behavior for visibility=public. However, it does not define the semantics of unlisted or aggregate_only beyond listing the enum values.

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 the exact operation ('change review visibility'), the resource ('one authenticated-user-owned review'), and the allowed visibility values. The mention of a stable experience_id helps distinguish this tool from list-oriented review tools and suggests a precise, single-review scope.

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

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

Provides a clear prerequisite workflow: use list_reviews_by_visibility first to map conversational list numbers to stable experience_id values. It does not explicitly discuss when to prefer save_experience or other siblings, but the core usage context is unambiguous.

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

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

Annotations already cover idempotency, non-destructiveness and non-read-only status, and the description adds valuable behavioral context: relationships affect broad search but never storage IDs, and the server independently validates structural writes. This aligns with the annotations, so there is no contradiction.

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

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

The first sentence is front-loaded and clear, but the description expands into a lengthy ontology policy about semantic heads, modifiers and compound types. Much of this guidance is useful yet not tightly scoped to the tool, making the description feel heavier than necessary for a 3-parameter operation.

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 3-parameter write with no output schema, the description covers prerequisites, server-side validation, storage-behavior implications and semantic misuse risks. It does not describe the return value or error cases, but the rich usage guidance makes the tool callable without needing additional context.

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

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

With 0% schema description coverage, the description must compensate; the 'ferry belongs_to transportation' example maps to source_type, target_type and relationship. However, it never explicitly defines the parameters, their formats, or the range of allowed relationship values, so parameter understanding still depends on inference from the example.

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

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

The description opens with a clear verb-resource pair: 'Add editable classification metadata between existing subject types,' and grounds it with an example ('ferry belongs_to transportation'). It also distinguishes this from resolving unknowns by directing those to resolve_subject_hierarchy, so the agent can tell it apart from related 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?

It states a clear prerequisite ('Unknown types must first be resolved with resolve_subject_hierarchy') and gives strong when-not-to-use signals ('This is a semantic assertion, not a naming choice'; descriptive modifiers belong in attributes/relationships). It does not explicitly route to inverse or alternative reclassification siblings such as retire_type_relationship, but the context is sufficient for most selections.

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

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

The description adds meaningful behavior beyond annotations: contributions are immutable, attribution and disagreement are preserved, votes are advisory, and the server independently verifies criteria and review IDs. The idempotentHint annotation already covers idempotency, so no repetition is needed. No contradiction exists.

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 compact and front-loaded: the core action and accepted types come first, followed by vote-specific constraints, then behavioral semantics. Every sentence adds distinct information without redundancy.

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

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

With nine parameters, nested objects, mutual exclusions, and no output schema, the description is too sparse. It does not explain idempotency_key semantics, how to reference review IDs, what response or confirmation the caller receives, or how immutability affects subsequent edits or corrections.

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, but it only elaborates the evidence parameter for votes. The other eight parameters—including required fields like deliberation_id, content, and idempotency_key—are left to name-based inference or the raw 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 names a specific verb and resource: 'Add an immutable proposal, critique, counterproposal, reconciliation or vote.' It also enumerates the exact accepted contribution types, which clearly differentiates this from sibling tools like create_deliberation or record_resolution.

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 clear context for when to use the tool and explicitly excludes one major use case: 'Votes are advisory and never resolve a deliberation or activate guidance.' It does not name an alternative tool, but the boundary is stated clearly enough for an agent to avoid misusing votes for resolution.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context about alias resolution, the distinction between naming and semantic disagreement, and server-side validation. It does not mention return format or pagination, but the annotations carry much of the safety burden.

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

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

The description is front-loaded with a clear purpose statement, but the latter half becomes a long policy discussion about semantic heads, modifiers, and server validation that goes beyond what is needed to invoke a parameterless listing tool. It is dense but overlong.

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

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

Given the zero-parameter schema, read-only annotations, and no output schema, the description adequately explains what the tool exposes and how to interpret aliases and identity. It does not explicitly detail the response shape, but the opening sentence names the returned content types.

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?

This tool has zero parameters and schema coverage is 100%, so the description has no parameter semantics to add. Baseline 4 is appropriate for a parameterless tool.

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

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

The description opens with a specific verb and resource: 'List canonical subject types, aliases, flexible relationships and reusable fields.' This clearly identifies what the tool does and distinguishes it from sibling classification and resolution tools by positioning it as the reference inspection operation.

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

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

The description explicitly says to inspect this before classifying an unknown subject type and before creating, selecting, relating, or proposing a subject type. This gives clear when-to-use context, though it does not explicitly name alternative sibling tools or provide when-not conditions.

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