TestGraph

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

Adds valuable behavioral context beyond annotations: two distinct model identities are required, agreement auto-confirms and locks the type, and the subject is not moved. With annotations already indicating idempotency and non-destructiveness, this description meaningfully explains the state-change mechanism.

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

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

Two tight sentences, each earning its place: first describes the core operation and threshold, second gives the selection condition. No padding or redundancy.

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

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

For a state-changing tool with five parameters and no output schema, it is mostly complete: the required parameters are inferable, the lock/confirm consequence is disclosed, and annotations cover safety. Minor gaps remain around evidence_fingerprint and return/error behavior, but the core invocation path is sufficiently 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?

Schema description coverage is only 20%, so the description must carry more weight. It adds meaning to source_model and evidence by describing 'independent AI model' and 'evidence-backed agreement', but it leaves evidence structure, reason purpose, and evidence_fingerprint semantics 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?

States a specific action ('submit evidence-backed agreement'), the target ('subject's existing provisional type'), and the meaningful consequence (two agreeing models auto-confirm and lock it). This distinguishes it from siblings like propose_subject_reclassification or get_subject_classification.

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

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

Gives an explicit trigger: 'Use this when the current type is already correct and no stricter descendant is justified.' It does not explicitly name the alternative tools or state when not to use it, 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?

Annotations already establish read/write and idempotency traits, and the description adds meaningful behavioral context: assertions are governed, new Places require a canonical key and durable identifier, coordinates must be WGS84, and geocoding is never done silently. These details go well 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?

Four concise sentences, each earning its place. The main purpose is front-loaded, followed by important preconditions and constraints. There is no fluff or repetition of schema details.

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

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

The tool is complex with 11 parameters, nested objects, and no output schema, yet the description covers only the core operation and a few critical constraints. It lacks return/confirmation behavior, failure semantics, and clarification of temporal/visibility parameters, leaving notable gaps for an agent trying to invoke it 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?

With 0% schema coverage, the description compensates partially by explaining key parameters: subject_id via 'existing eligible subject', source via 'source provenance', object_place via canonical key/identifier requirements, and value via WGS84/no-geocoding constraints. However, several parameters such as predicate values, qualifiers, validity windows, observed_at, and visibility receive no semantic guidance.

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

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

The description clearly states the action ('Add') and the resource ('a governed location assertion') for an existing eligible subject. It is specific enough to distinguish this tool from siblings like get_location_assertions and resolve_location_assertion, and it highlights the unique aspect of evidence-backed, governed assertions.

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 useful preconditions: resolve the subject and any existing Place first, and requires source provenance for every assertion. It does not explicitly name alternative tools or state when not to use this tool, but it does imply the sequencing needed for correct use.

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 reveals atomicity, idempotent retries, the DELIBERATION_ALREADY_CLAIMED error for other clients, and the fact that claiming grants no authority outside the stored deliberation scope. These are valuable behavioral details the structured data cannot express.

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

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

Three sentences, with the main purpose front-loaded and each subsequent sentence adding distinct behavioral context. There is no redundancy or 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 claim operation, the essential behavior and failure mode are covered clearly. The main missing context is the purpose of source_model and a pointer to a sibling like list_open_deliberations for finding eligible IDs, but these are minor against the strong behavioral disclosure.

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 never references idempotency_key or source_model by name. While 'Repeating the same claim is safe' hints at idempotency behavior, it does not explain how to populate the key or what the optional source_model parameter means, leaving a significant gap.

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

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

The description names a specific verb and resource: 'Atomically claim an open deliberation for the authenticated MCP client.' This clearly distinguishes claiming from creating, reading, or listing deliberations, and 'atomically' adds precision about the 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 gives clear context: use this when you need to claim an open deliberation, not merely read or list one. It does not explicitly name sibling tools or say 'use list_open_deliberations first,' 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 destructiveHint and idempotentHint annotations, the description discloses that the server 'preserves an immutable correction record in subject provenance' and that authoritative evidence and a reason are mandatory. This gives the agent important behavioral context about side effects and auditability that annotations alone do not provide. 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?

The description is two sentences with no filler. Each sentence adds distinct information: the operation and its preconditions, then the alternative and a prohibition. The most important guidance is front-loaded.

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

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

Given the complexity of an 8-required-parameter destructive mutation with no output schema, the description covers the core contract well: what is replaced, what must match, what is mandatory, and what alternative to use. It leaves minor gaps such as exact behavior when expected_value does not match and the shape of any response, but these are secondary to safe invocation.

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

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

With schema description coverage at only 13%, the description compensates partially by explaining that expected_value must match the current value, evidence_sources and reason are mandatory, and subject_id is the stable key. It does not explicitly explain every parameter, such as idempotency_key or corrected_value, but the operation-level explanation and schema names carry enough meaning for correct invocation.

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

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

The description opens with a specific verb and resource: 'Replace one incorrect identifier or attribute using the stable subject ID.' It clearly distinguishes this correction operation from the sibling enrich_subject by explicitly naming it and stating it should be used for missing facts.

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-not-to-use guidance: '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, making the correct invocation context 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?

Beyond the idempotentHint annotation, it discloses meaningful behavior: stored content is advisory and not authority for external actions, and proposals remain inactive until explicit user approval. This is substantive, though it does not detail approval mechanics or authentication requirements.

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

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

Each sentence earns its place: purpose, canonical-key advice, advisory-scope caveat, governance recipe, and approval state. The most important action is front-loaded before the detailed special-case instructions.

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

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

For an 8-parameter tool with nested context and no output schema, it covers the critical workflow, including the special governance case and activation state. It stops short of describing idempotency-key behavior and return values, but that is a modest 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?

With only 13% schema description coverage, the description carries most of the parameter burden. It usefully explains canonical_key and context governance fields, but leaves required idempotency_key and optional constraints/acceptance_criteria unexplained in both schema and 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: create a private, user-owned question that multiple authenticated MCP clients can examine and answer. This clearly distinguishes creation from retrieval-focused siblings like get_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 gives concrete usage guidance: use a stable canonical_key for later retrieval and provides an explicit recipe for proposing induction-guidance changes through context fields. It does not explicitly say when not to use this tool, but the context is clear enough for an agent.

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

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

Annotations already flag destructive and idempotent behavior, and the description adds substantial context: permanence, server-enforced ownership, cascading deletion of dependent AI assessments, conditional subject deletion, and confirmation policy. This 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?

The description is dense but every sentence carries operational weight: permanence, ownership, cascading effects, subject preservation conditions, and no double confirmation. It is front-loaded with the most important constraint and has no fluff.

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, the description covers the essential invocation context: authorization, ownership, cascading deletion, and conditional side effects. It leaves minor gaps around idempotency_key behavior and error/response handling, but the overall picture is strong.

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

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

Schema description coverage is 0%, so the description must compensate. It makes confirm_deletion meaningful through 'explicitly requests deletion' and explains the orphan-subject condition, but it never maps these to the actual parameter names, omits the idempotency_key semantics, and does not state what happens if confirm_deletion is false.

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 action and resource: 'Permanently delete one review' with a clear user-ownership constraint. It differentiates from siblings like save_experience and set_review_visibility by emphasizing permanent deletion of a single review.

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 explicitly states when deletion is appropriate: only after the authenticated user explicitly requests it, and it instructs not to ask for a second confirmation when authorization is already explicit. It also clarifies that users cannot delete others' reviews, though it does not name alternative tools or edge cases where deletion should be refused.

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 repeatedly instructs web retrieval and web search: 'Use your full available reasoning, web retrieval and tool capabilities' and 'use web search to find the authoritative source surfaces.' Annotations set openWorldHint to false, indicating no open-world/internet access. This is a direct annotation contradiction, making the behavioral signal unreliable despite otherwise useful idempotency and preservation notes.

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 very long unstructured paragraph; the core action is buried after an openging motivational sentence about being an 'op-en-ended semantic and discovery engine.' Several directives repeat (do not omit members, do not ask permission, batching rules) and would benefit from headings or bullets.

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 definition is remarkably complete for a complex nested write tool with no output schema: it covers workflow.next_action, idempotency, concurrency, collection traversal, source manifests, and evidence reporting. The completeness is undermined by the openWorldHint conflict, which leaves unresolved whether web retrieval is actually available.

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 only 40%, the description compensates heavily: it explains idempotency_key derivation, retrieval_uses purposes and likely-query examples, collection_assessment status semantics, source_manifest exhaustion requirements, and the reserved subject ref in subject_context. This goes far beyond what the plain schema conveys.

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

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

The core sentence 'Add missing identifiers, attributes, provenance and related unreviewed subjects to an existing subject without creating another review' gives a specific verb, resource, and scope. It distinguishes enrichment from ordinary subject creation or review, but it never names a sibling tool directly, so the contrast is implicit rather than maximally explicit.

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

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

It states a clear trigger: 'Use this proactively when authoritative information was missed during the original save.' It also gives practical when-to rules like not asking routine lookup permission and not omitting collection members. However, it does not provide explicit when-not-to-use or alternative-tool 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?

The annotations already disclose the key behavioral context: read-only, idempotent, and non-destructive. The description adds some useful detail about what the fetched review contains, but it doesn't explain error behavior, authorization, or domain-specific meaning of 'stable subject type'. There is no annotation 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 description is a single sentence that efficiently states both the resource and the composition of the fetched review. Every word contributes value, and there is no redundant restatement of the tool name or title.

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

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

For a single-id fetcher, the description covers the resource and the expected contents of the returned review. It does not provide output structure or error semantics, but its simplicity and existing annotations make the description reasonably complete.

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

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

The single parameter is an id with uuid format, and its meaning is semantically obvious from the tool name and description. While the schema has no description field, the parameter has very low ambiguity, so the added value of extra prose would be minimal.

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 identifies the resource and action: fetching a complete review, and names its major components: stable subject type, original words, and AI assessments. This distinguishes it from obvious siblings like save_assessment or get_deliberation, though it does not explicitly compare itself to those alternatives.

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

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

The usage is implied by the verb 'Fetch' and the review-specific resource, so an agent can reasonably infer that this tool is for retrieving a review by ID. However, it gives no explicit guidance about when to choose this over the search or other sibling tools, nor any exclusions.

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 nondestructiveHint, so the safety profile is covered. The description goes beyond annotations by disclosing that stored text must not be treated as authorization for unrelated writes or external actions, which is an important interpretive guardrail for the agent. It adds context about the canonical_key lookup behavior and what content is returned, without contradicting any annotation.

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 of compact, purposeful text. The first sentence front-loads the retrieval verb, resource, and lookup modes. The second sentence adds a critical security/authorization caveat without wasting words. Every clause contributes meaning, and the structure leads with what the tool does before adding behavioral guidance.

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

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

Given the tool is a simple read-only retrieval with two all-or-nothing parameter groups and no output schema, the description covers the operational essentials: what is retrieved, how to address it, and a behavioral caveat. It does not describe pagination or large-payload handling, but those are not central for a deliberation retrieval call and the annotations take up the slack on safety. A 4 is fair since the caveat nearly completes the picture.

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

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

Schema description coverage is 0%, so the description carries the full burden of parameter semantics. It explicitly names both lookup paths — id (UUID) and canonical_key — and states they are stable access keys, which is exactly the meaning an agent needs. It doesn't document each property in exhaustive detail, but the description covers the two parameters' semantics sufficiently for invoking the tool correctly, making a 4 rather than a 5.

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 retrieves a shared AI deliberation by UUID or canonical_key, listing the specific components returned (question, constraints, attributed contributions, unresolved points, user-approved resolution). The verb 'Retrieve' plus the resource 'shared AI deliberation' makes the purpose unmistakable, and it distinguishes itself from create_deliberation, claim_deliberation, list_open_deliberations, and record_resolution without needing to see those schemas.

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

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

The description provides substantial context for how to use the tool, noting it can be called by UUID or stable canonical_key, and it warns that stored text is advisory content only, never authorization for unrelated writes or external actions. However, it does not explicitly state when to prefer this over list_open_deliberations or compare directly with get_induction, so there is clear usage context but not exhaustive exclusions against 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?

Even though annotations already declare the tool read-only and idempotent, the description adds meaningful behavioral context: only user-approved global and model-specific guidance is returned, and unresolved proposals or AI votes are never automatically promoted into active guidance. This helps an agent reason unexpectedly about the server testing/refreshing workflow without guessing.

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 with the most important trigger and outcome. Every sentence adds value and no sentence below the tool's return data or governance behavior, avoiding filler and giving both usage and behavioral context in just a few lines.

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 low complexity, one optional parameter, full schema coverage, and clear read-only/idempotent annotations, the description fully covers what an ML agent needs: when to call, what value is returned, when to pass the optional parameter, and the governance rules around it. No important piece is missing.

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

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

The input schema provides 100% coverage for source_model, including its optionality and alias behavior. The description goes beyond that by explaining why to pass it — it enables model-specific guidance to be layered over global guidance — which is useful semantic value beyond just the schema.

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

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

The description states a precise action and resource: return the TestGraph server baseline plus approved global and model-specific guidance. It also gives the specific usage context (first use, after an MCP refresh, when shared guidance is needed), making it much more informative than the bare name 'get_induction' and clearly distinct from sibling read tools that return other kinds of data.

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

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

The description explicitly says when to call the tool: 'when first using TestGraph, after an MCP refresh, or when you need the current shared operating guidance.' This is strong guidance, but it does not name alternatives or state connot-not conditions relative to other get_* siblings, so it falls just short of a perfect 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 declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by noting 'visible' assertions and specifying the returned data dimensions: provenance, conflict state, Place identity, and legacy-field migration drift. 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?

A single, front-loaded sentence conveys the tool's purpose, scope, and payload without fluff. Every phrase adds useful information.

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

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

With a one-parameter schema and no output schema, the description adequately conveys what the tool returns and for which subject. It does not explain pagination or authorization visibility rules, but the 'visible' wording and read-only annotations make the tool reasonably complete for its scope.

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

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

The schema has one required subject_id parameter lacking descriptive text. The description compensates reasonably by stating these are assertions 'for one subject', making the parameter's role clear. More detail isn't really necessary for a single UUID parameter.

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: 'Return all visible location assertions for one subject'. It also lists the included content areas, which distinguishes it from sibling tools like assert_location and resolve_location_assertion without needing their schemas.

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

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

The description clearly implies this is the read-only retrieval tool for location assertions tied to one subject. However, it does not explicitly state when to prefer this over related tools like resolve_location_assertion or get_deliberation, nor does it provide exclusions.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: it returns the exact build version and live deployment identity, and it explicitly names the fields build_sha and deployment_id. This goes beyond the annotations by explaining what the agent will actually receive and how to validate it.

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, each earning its place: the first states the exact purpose, the second gives when to use it, and the third provides concrete cross-checking guidance. The key diagnostic intent is front-loaded, with no filler or redundancy.

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

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

For a zero-parameter diagnostic tool with strong annotations, this is complete. It tells the agent what this tool returns, when to invoke it, when not to bother, and how to verify the returned values. No output schema exists, but the description names the expected fields and suggests a comparison endpoint, covering the essential 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?

The input schema has zero parameters, and schema description coverage is 100% (vacuously). With no parameters, the description does not need to explain arguments. The baseline for 0-parameter tools is 4, and the description correctly focuses on the result and use case instead.

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 ('Return') and a precise resource ('exact TestGraph MCP server version and live deployment identity'), then immediately ties it to diagnostics. This clearly distinguishes it from the sibling tools, which all concern subject classification, deliberation, or experience records.

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 states when to use this tool: 'checking a stale connection, endpoint mismatch or deployment issue.' It also gives a negative condition: 'ordinary writes do not require a preceding version probe.' The troubleshooting advice to compare build_sha and deployment_id with the public /version endpoint further clarifies its intended role.

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 context beyond annotations by revealing that classifications are locked and that a decision audit accompanies the state.

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

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

Two sentences, both purposeful: the first states the operation and output, the second states the locking policy. No filler or redundant restatement of the tool name or title.

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

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

For a simple single-parameter read with rich annotations, the description conveys the main returned content: current classification state and decision audit. It does not describe the audit structure or response format in detail, but no output schema exists to fill that gap; this is a minor deficiency given the low tool complexity.

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

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

Schema description coverage is 0%, and the description does not mention subject_id at all or clarify how it identifies the subject whose classification is read. The schema only provides a required UUID format, so the description fails to compensate for the missing parameter guidance.

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

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

The description opens with 'Read the current classification state and its decision audit,' which clearly identifies a specific verb and resource. The warning that confirmed classifications are locked distinguishes this lookup from sibling tools like propose_subject_reclassification or reopen_subject_classification.

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 establishes when this tool is appropriate for reading settled classification state and explicitly says confirmed classifications must not be routinely reassessed. However, it does not name alternative tools or spell out when to prefer this over related reads like get_deliberation or resolve_subject.

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 readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: results are redacted, scoped to the authenticated user, and explicitly exclude raw conversations or secrets. This helps the agent set expectations about privacy and content.

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 tight sentences, front-loaded with the action and resource, and includes only clarifying details about return content and exclusions. No wasted words or redundancy.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description covers scope, redaction, and return content. The only minor omission is how 'limit' controls pagination or count, but this is low risk given the simple schema and annotations.

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 only parameter, 'limit', at all. The agent must infer its meaning from the parameter name and numeric constraints (default 50, min 1, max 200). With low coverage, the description should compensate but does not.

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 resource ('the authenticated user's structured, redacted MCP interaction telemetry'), and clarifies what it returns and explicitly excludes. This clearly distinguishes it from sibling list tools like list_my_workflows or list_reviews_by_visibility, which target different domains.

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 usage for retrieving a user's interaction audit, but offers no explicit when-to-use guidance, exclusions, or alternatives. With siblings like list_my_workflows and list_reviews_by_visibility, an agent must infer from scope rather than being routed by the description.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context: the state is durable, server-owned, tied to the authenticated user, and includes pending, disputed, and completed procedures. 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?

Two sentences deliver the core action and the primary use case with no filler. The description is front-loaded, clear, and every sentence earns its place.

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

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

For a simple, read-only list tool with one optional parameter, no output schema, and strong annotations, the description gives enough scope and use-case context for an agent to decide to call it. It slightly lacks detail on the limit parameter's effect and the exact return shape, but those are minor given the tool's simplicity.

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 single 'limit' parameter has no schema description (0% coverage), and the description never explains what limit controls or how it affects results. With such low schema coverage, the description should compensate, but it does not; only the parameter name, default, and bounds give any hint.

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

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

States a specific verb ('List') and a specific resource ('durable server-owned workflow state') scoped to the authenticated user. The mention of 'pending second-model work, disputes and completed procedures' also helps differentiate it from sibling list tools such as list_open_deliberations and list_my_mcp_interactions.

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 an explicit usage instruction ('Use this to inspect...') with concrete scenarios, telling the agent when this tool is appropriate. However, it does not mention alternatives or when not to use it, stopping just short of a full 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 establish read-only, idempotent, and non-destructive behavior. The description adds meaningful extra context: results are scoped to the current user, model label aliases are normalized, and the tool exists to avoid requiring an identifier. 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, each earning its place: it states the resource and purpose, gives filtering guidance tied to a sibling workflow, and records alias behavior. There is no padding 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 read-only listing tool with no required parameters, the description is sufficient to guide correct invocation. It does not describe the return shape, but no output schema is provided and the list semantics are clear enough to make that omission 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 low at 33%, but the description compensates for target_model and unclaimed_only by giving them operational meaning. The limit parameter still relies only on its schema defaults and bounds, so its semantics are not significantly deepened.

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

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

States a specific verb and resource: 'List this user's open deliberations.' The description also explains the purpose is discovery without a UUID or canonical key, which clearly distinguishes this from sibling tools like get_deliberation and resolution-oriented 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?

Provides clear contextual guidance: use target_model to filter by model label and unclaimed_only before claiming work. It also records the alias behavior for gpt and chatgpt. However, it does not explicitly say when an alternative like get_deliberation should be preferred when a UUID is already available.

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 as safe, and the description adds meaningful behavioral context beyond them: returns stable experience IDs, returns display-only positions, and explicitly warns that later mutations must use experience_id rather than position. This is critical non-obvious behavior that prevents misuse.

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

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

Two tight sentences with no filler. The first sentence front-loads the action and output; the second delivers an essential caveat about position versus experience_id. 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 one enum parameter and no output schema, the description is complete enough: it states the return content, explains the display-only nature of positions, and gives the required mutation guidance. An agent can call this tool correctly and interpret its results without missing critical 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?

Schema coverage is 0%, so the description must compensate. It clarifies that the visibility parameter selects one of the visibility states and scopes results to the authenticated user's reviews. It does not explain each enum value, but the enum is self-descriptive in the schema, and the single parameter's role is sufficiently conveyed.

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'), names the exact resource ('the authenticated user's reviews'), and scopes the operation to 'one visibility state.' It also specifies what is returned (stable experience IDs plus 1-based positions), clearly distinguishing this from sibling tools like set_review_visibility 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?

The description provides clear context: use this tool to retrieve the authenticated user's reviews filtered by a single visibility state. It does not explicitly name alternatives or state when not to use it, but the intended use case is unambiguous and the guidance about positions being display-only helps the agent use the output appropriately.

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 annotations: one model creates a candidate, agreement by two distinct models automatically moves the subject, confirms and locks it, and a locked subject is not reopened by later opinions. It also warns that the server independently validates structural writes. This gives an agent a clear mental model of side effects, which is especially valuable because the annotations only provide idempotent/destructive hints.

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

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

The first sentence is front-loaded and states the core action. The later policy sentences about semantic heads, modifier categories, and compound-type exceptions are relevant and earn their place for this domain. The description is longer than average but not bloated, and the structure moves from mechanism to vocabulary rule to server enforcement logically.

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 consent/locking mechanism, vocabulary constraints, and server-side validation well, which is a lot for a proposal tool with no output schema. It leaves a small ambiguity: what happens while a candidate is pending or if the two-model agreement condition is not met. Overall, an agent has enough to call it correctly, but not every outcome is explicit.

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%, so the description must compensate. It richly explains target_subject_type with the strict-descendant, semantic-head, and modifier guidance, and source_model is already described in the schema. However, reason and especially evidence_fingerprint are not meaningfully defined beyond the schema, and evidence is only vaguely described as evidence-backed, leaving a gap for a low-coverage 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: submit an evidence-backed refinement to a strict descendant type. It separates this from a plain type selection or affirmation by emphasizing that one independent model creates a candidate, which is a distinct action from affirming or moving a subject. It does not explicitly name a sibling alternative, so it falls short of a 5.

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

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

The description gives clear context for when to use this tool: before proposing a subject type, identify the semantic head and modifiers, and avoid using material, arrangement, quantity, colour, size, location, or purpose/use in type names. It also explains when a compound may remain a distinct type. It does not explicitly state 'use X instead for affirmations' or give a formal when-not-to-use list, but the guidance is strong.

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 important behavioral traits beyond the annotations: it does not infer consensus, it records accepted contributions and remaining disagreement, it requires user_approved=true, and only user-approved resolutions can activate guidance for induction deliberations. This meaningfully supplements readOnlyHint=false, idempotentHint=true, and destructiveHint=false.

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

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

The description is concise and front-loaded: it states the core action first, then the key behavioral caveat, then the domain-specific side effect. Every sentence adds meaning, and there is no redundant or filler 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?

Given 7 parameters, no output schema, and only basic annotations, the description covers the essential decision semantics, the user-approval requirement, and the important get_induction activation effect. It does not cover error behavior or what happens when user_approved=false, but the core usage context is well specified.

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

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

The schema has 0% description coverage, so the description carries more responsibility. It helps by mapping 'accepted contributions' to accepted_contribution_ids, 'remaining disagreement' to unresolved_points, and stating user_approved=true. However, it does not explain idempotency_key, rationale, or the exact expected form of resolution, so it only partially compensates for the missing schema 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 uses a specific verb and resource: 'Close a deliberation with the user's explicit decision.' It also clarifies that the tool does not infer consensus, which helps distinguish it from related deliberation operations. However, it does not explicitly name or contrast a sibling tool, so it stops short of full differentiation.

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

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

The description gives clear context for when this tool is appropriate: it records the user's explicit decision and requires user_approved=true. It also explains when the resolution has downstream effect, such as becoming active guidance for induction-guidance deliberations. It does not explicitly state when not to use it or name alternatives, but the preconditions are 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds concrete behavioral context: that valid existing fields are attached automatically on first use, and that one-off narrative details are better served by raw_text. This goes beyond the annotation hints and clarifies side effects (automatic attachment) and a preference for a different mechanism, 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?

The description is three sentences long, with the purpose front-loaded in the first sentence. The second sentence handles a common user-confirmation pitfall, and the third offers a clear alternative. No word is wasted, and the structure is logical. It could be slightly more organized by breaking into bullet points, but it's appropriately 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?

Given the tool has 5 parameters, a nested object, and no output schema, the description is insufficient for an agent to invoke it correctly without additional knowledge. An agent would need to understand what a canonical field is, what json_schema should look like, what subject_types expects (presumably type names), and the format for aliases. The description covers purpose and one behavioral nuance but leaves parameter semantics largely undefined, making the tool hard to use correctly in autonomous 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?

The input schema has 5 parameters (aliases, description, json_schema, subject_types, canonical_name) with 0% schema description coverage. The description does not clarify the meaning or format of any parameter. It hints that subject_types is related to pre-attaching fields, but it doesn't explain what json_schema should contain, what canonical_name represents, or the nature of aliases. With zero coverage, the description must compensate, and it fails to do so.

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: to register a genuinely new canonical field or explicitly pre-attach one to subject types. This is a specific verb-resource pair that distinguishes it from all sibling tools (no other tool handles field registration). It even clarifies the two distinct use cases, leaving 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 gives clear usage context: it tells the agent not to ask for confirmation when reusing an existing canonical field (because attachment is automatic) and explicitly recommends raw_text for one-off narrative detail. This provides a when-to-use and an alternative, though it doesn't enumerate all scenarios where this tool should be avoided beyond existing fields. Still, it's strong guidance for routing decisions.

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 convey idempotency and non-destructiveness. The description adds a useful semantic nuance—alias use does not constitute a semantic conflict—but does not disclose further runtime behavior such as conflicts with existing aliases or effects beyond registration.

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 instruction is front-loaded and the whole description is short. Slight redundancy exists between 'genuinely equivalent' and 'genuine naming equivalence,' but the text otherwise stays focused and readable.

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

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

For a two-parameter alias registration protected by annotations, the description covers what to register, the stability requirement for the subject type, and the semantic boundaries. It omits examples or conflict behavior, but no output schema exists and idempotency is already annotated, so nothing critical is missing.

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

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

Schema has 0% description coverage, so the description carries the burden. The phrase 'equivalent expression' maps to alias and 'existing stable subject type' maps to subject_type, providing semantic roles the bare string schema lacks.

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 object—'Map a genuinely equivalent expression to an existing stable subject type'—and immediately distinguishes the operation from a category relationship, separating it from sibling tools like set_type_relationship or propose_subject_reclassification. This leaves no doubt that the tool registers naming equivalence, not taxonomy.

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 explicitly tells an agent when to use the tool ('genuine naming equivalence') and when not to ('Never use this to express a category relationship'). It does not name alternative sibling tools, so the guidance is clear context but not a fully explicit decision tree.

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

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

No annotation gives behavioral covere, since all hints are false, so the description must carry this burden. It does add a meaningful constraint: only specific triggers reopen a confirmed classification, and ordinary disagreement is permanently excluded. However, it does not explain side effects, workflow consequences, reversibility, or the role of the user_approved flag.

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, the key action and policy front-loaded, with zero filler. Every clause contributes: the first enumerates valid use cases and the second strips away the most likely misuse case.

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 five parameters, 0% schema coverge, no output schema, and no annotation assitance, the description does not provide enough to call the tool correctly. An agent cannot determine what evidence should look like, what reason text is expected, what user_approved does, or what happens after a successful reopen.

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_coverge is 0%, so the description must compensate, but it only paraphrases the trigger enum values. It adds no meaning for the required reason, evidence, subject_id, or the optional user_approved parameter, leaving an agent with insufficient guidance for most of the input surface.

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

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

States a specific verb ('Reopen'), a specific resource ('confirmed classification'), and the exact limited circumstances under which the action applies. The phrase 'Ordinary later disagreement never reopens it' further differentiates this from related reclassification/proposal tools by establishing a clear boundary.

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

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

Gives explicit when-to-use criteria by enumerating the four accepted triggers and an explicit when-not-to-use rule: ordinary later disagreement. It does not name an alternative tool such as propose_subject_reclassification, so an agent must infer the alternative from the sibling list 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 carry the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely useful behavioral context beyond them: the explicit-user-approval requirement for the submitting client. This aligns with the user_approved parameter and is the kind of auth/approval constraint the rubric credits. No contradiction with annotations exists, though post-resolution effects are left undisclosed.

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

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

Two sentences with zero filler: the first states the operation, the second a binding constraint, and the purpose is front-loaded. Every sentence earns its place, though the second could arguably have been spent on parameter documentation given the 0% schema coverage.

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

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

For a 5-parameter mutation with 0% schema coverage, 4 required inputs, and no output schema, the definition is incomplete: what rationale should contain, how assertion_id is obtained, how idempotency_key works, and what resolution changes about the assertion are all unaddressed. The description covers purpose and one approval constraint but leaves the agent guessing on major inputs.

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 5 undocumented parameters — it barely does. It alludes to assertion_id and user_approved ('its own contested claim', 'explicit user approval') but leaves rationale content, idempotency_key purpose, and the decision enum semantics effectively unexplained. Even the allusions are indirect rather than explicit parameter mappings.

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 pair ('Accept or reject') with a clear resource ('a contested location assertion'), making the operation immediately understandable. The qualifier 'contested' distinguishes this from creating assertions (assert_location) and from resolving subject classifications (resolve_subject, resolve_subject_type), though it does not name those siblings explicitly. A 5 would require explicit sibling differentiation, so 4 is appropriate.

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

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

The second sentence establishes real usage context — the submitting client cannot resolve its own contested claim without explicit user approval — which signals the scenario this tool serves. However, no alternative tools are named and no exclusion criteria are given, despite a crowded sibling set of resolve_* and record_resolution tools that an agent must distinguish between. Usage is implied rather than explicitly routed.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false. The description adds useful context about matching and existing-subject reuse, but does not disclose no-match behavior, result shape, or pagination. No contradiction with annotations is present.

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 main action and is fairly tight. Some redundancy exists between the first and third sentences, both emphasizing lookup before creation, but each sentence adds matching or reuse context.

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 provides enough orientation to select the tool and understand why it should be called. Since there is no output schema, more detail about what the returned subjects look like or how absence of a match is handled would improve completeness.

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 parameter-documentation burden. It gives semantic meaning for canonical_key, name, subject_type, and identifier_value, but it does not explain limit, identifier_key, or the anyOf constraint saying that at least one selector must 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 clearly identifies the tool as a lookup operation for an existing subject and lists several match types: canonical key, name, and identifier. It also frames the purpose as pre-creation deduplication. It does not explicitly differentiate from similar siblings like resolve_subject_type or resolve_subject_hierarchy, but the resource and action are clear.

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 timing guidance: use this before adding or declaring a new subject so the existing subject_id and canonical_key can be reused. It does not spell out when an alternative sibling should be used instead, but the recommended workflow 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?

The description adds substantial behavioral context beyond the annotations: the server reuses existing entries, creates only missing provisional nodes, adds belongs_to relationships, rejects cycles, and independently validates structural writes. This is exactly the kind of non-obvious behavior an agent needs to invoke the tool safely and predictably, and it does not contradict the idempotent or non-destructive hints.

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

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

The description is front-loaded with the prerequisite and example, then gives important modeling rules. It is longer than average, but most of the content about semantic heads, naming variants, and attribute-like modifiers directly affects correct term selection. A few points are restated in slightly different ways, which prevents a 5.

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

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

Given the complexity of semantic hierarchy resolution and the minimal schema, the description covers the necessary invocation context: when to use it, how to order terms, what the server does, what to avoid, and how to distinguish genuine concepts from naming variants. No output schema exists, but the description is sufficient for an agent to select and 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 schema has only one parameter, `terms`, with 0% description coverage, so the description must carry the semantic weight. It does so by requiring broad-to-specific ordering, providing the example ['food','recipe'], and explicitly forbidding 'review'. It could add a bit more about formatting or dictionary matching, but it is strongly useful for a single-parameter 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 clearly states a specific operation: given a broad-to-specific list of terms, resolve a semantic subject hierarchy by reusing existing entries and creating missing provisional nodes. It also distinguishes itself from sibling tools by tying its use to vocabulary_index and by describing hierarchy-level behavior (belongs_to relationships) rather than single-type or instance 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?

It gives an explicit prerequisite: use after vocabulary_index when the specific subject type does not yet exist, and it provides a clear exclusion ('review'). However, it does not explicitly name alternative sibling tools such as resolve_subject_type or explain when those should be used instead, so it stops short of full alternative routing.

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

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

The description discloses meaningful normalization behavior that annotations do not cover: case, punctuation, possessives, and ordinary plurals are normalized mechanically. It also clarifies that equivalent aliases are valid and that the returned stable subject-type ID is the identity boundary.

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 with the core purpose: 'Resolve flexible input to one stable subject-type ID.' Each sentence adds meaningful detail about normalization, alias validity, and the returned identity without redundant packaging.

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

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

For a single-parameter, read-only, idempotent lookup tool, the description covers the essential behavior: input flexibility, normalization rules, alias handling, and the return value. The annotations already cover non-destructiveness and idempotency, so the description does not need to repeat those.

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

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

The schema has zero description coverage for the single `term` parameter, but the description compensates by explaining what kind of input is accepted and how it is normalized. It does not provide explicit examples, but the meaning of `term` as a flexible subject-type label is clear enough for this simple single-parameter 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 and resource: resolving flexible input into a stable subject-type ID. It clearly distinguishes from similar siblings like resolve_subject by emphasizing the output is a subject-type ID, not a subject ID.

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 this tool is appropriate: any flexible, non-canonical input needing a stable subject-type ID. It explains that aliases and non-canonical wording are acceptable, but it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark the operation as destructive and idempotent, and the description adds meaningful context: the edge becomes a rejection tombstone, preserving subject type/subjects/reviews and blocking silent recreation. This goes beyond the annotations and clarifies the operation's side effects.

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 dense sentences with no filler. The core action is front-loaded, and the crucial tombstone side-effect is placed second for emphasis.

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

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

The tool has four parameters with zero schema descriptions and no output schema, and the description does not compensate for the missing parameter semantics. It does clarify the tombstone effect and preservation behavior, but an agent would still be uncertain how to populate source_type and target_type correctly.

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

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

Schema description coverage is 0% and the description never explains source_type, target_type, relationship, or reason. An agent must infer everything from parameter names alone, which is inadequate for a tool that retires a specific semantic relationship.

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—retire exactly one semantic relationship—and names what is preserved: subject type, subjects, and reviews. The title and wording clearly distinguish this from related siblings like set_type_relationship or propose_subject_reclassification by emphasizing retirement and rejection tombstone behavior.

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 this tool is for retiring an incorrect classification and preventing silent recreation, but it does not explicitly state when to use it versus alternatives. There is no mention of when not to use it or which sibling should be chosen instead.

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

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

Annotations already mark it idempotent, and the description adds meaningful detail by specifying deterministic idempotency-key derivation and safe retry/restart semantics. It also discloses concurrency batching and dependency ordering, which are not visible in the schema or 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 purpose first, concurrency guidance second, and idempotency semantics last. Every sentence earns its place and there is no filler.

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

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

Idempotency and concurrency behavior are well covered, and annotations cover the safety profile, but the description omits definitions for most payload parameters, possible values, and return/error behavior. With no output schema and 0% parameter coverage, an agent cannot confidently populate analysis versus evidence or know valid assessment_type values.

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 by explaining the 8 parameters. It only elaborates idempotency_key and loosely alludes to a canonical subject key; analysis, evidence, conclusion, confidence, source_model, assessment_type, and experience_id have no semantic explanation beyond raw types.

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

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

States a specific verb ('Save'), a distinct resource ('separately attributed AI analysis'), and anchors it to the exact review it evaluates. This differentiates it from generic tools like save_experience and gives an agent a clear sense of what this tool is for.

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 purpose implies when to use it, but the description never explicitly names alternatives or exclusion criteria. The concurrency batching guidance is operational rather than tool-selection guidance, so when to choose this over save_experience or submit_contribution is left to inference.

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

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

Adds substantial behavior beyond annotations: idempotency-key derivation, retry semantics, concurrent batching up to 10, server-side manifest verification, warnings on partial/unknown coverage, and the experienced_at default. There is no contradiction with annotations; the idempotentHint is expanded rather than merely repeated.

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 long unstructured paragraph that repeats the shared-graph and future-search rationale multiple times and includes vague filler such as using 'full available reasoning, web retrieval and tool capabilities.' More disciplined formatting and deduplication would make the dense rule set far easier to apply.

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 covers the tool's contract: mandatory enrichment and collection assessment, idempotency and retry behavior, server verification and warning cases, batching limits, and the exact conditions for unavailable or not_applicable. An agent has nearly everything needed to invoke it 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?

With only 18% schema coverage, the description compensates by explaining the mandatory nested objects (subject_enrichment_check, collection_assessment, submitted_member_refs, applied_fields, retrieval_uses) and the meaning of canonical_key and idempotency_key. A few self-explanatory string fields such as headline, summary, raw_text, and visibility are left to the schema, so it is not a 5.

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

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

Opens with a specific verb-resource pair: 'Save a review against an already-resolved stable subject type.' The title reinforces approved-review scope, and the body repeatedly ties the operation to saving an experience with mandatory enrichment, distinguishing it from siblings like save_assessment or enrich_subject.

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 rich context: it names the precondition of an already-resolved subject type, mandates enrichment and collection assessment before saving, and tells the agent when to retry automatically versus ask the user. It does not explicitly name sibling alternatives or exclusion conditions, so it stops just 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?

The description contradicts the annotation openWorldHint=false. The annotation signals a closed-world tool where absence in results is meaningful, but the description explicitly says 'A search miss for one label is not evidence that the underlying subject or concept is absent' and only coverage_status=complete permits concluding absence. This is an annotation contradiction that overrides any otherwise useful behavioral disclosure.

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

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

The definition is front-loaded with the core purpose and contains genuinely valuable detail, but it is noticeably repetitive: 'lexical rather than semantic' appears more than once and the 'one keyword, then exact search, then fetch' instruction is restated. It is acceptable but not tight.

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

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

For a tool with no output schema, this description generously covers the main contract: what is searched, why keyword misses are unreliable, cursor/has_more pagination, collection_coverage semantics, and the special location-recommendation procedure. It lacks a full return-shape description, but the coverage and example constraints make it largely sufficient.

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 only 20%, the description adds useful meaning for query, subject_type, and cursor, such as keyword-first search, type-only fallback, and pagination. However, it gives no explicit clarification of limit or include_related semantics, so parameter-level compensation is only partial.

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

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

The opening sentence names a concrete verb and resource: 'Search reviews plus matching reviewed or unreviewed subjects.' It also clarifies lexical rather than semantic search and the subject/review scope, making it distinguishable from sibling tools like fetch or the submission/assertion 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 operational guidance: start with one discriminating keyword, follow up with exact subject-name searches, fetch every returned review, paginate until has_more is false, and use coverage_status to determine absence. It does not explicitly contrast this tool with sibling alternatives, but its usage context is otherwise strong.

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 a meaningful side effect: setting visibility to public also ensures publication_status=published. It also clarifies the ownership scope ('authenticated-user-owned'). No contradiction with the annotations exists, though it does not detail other potential state changes beyond public visibility.

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

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

Three compact sentences, each serving a purpose: core action, ID acquisition guidance, and an important side effect. The most critical information is front-loaded, with no filler or redundant restatement of the schema.

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

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

For a two-parameter mutation tool without an output schema, the description is largely complete: it names required parameters, shows how to obtain the ID, and flags a non-obvious publication side effect. Minor missing context includes possible error conditions or response format, but these are not critical for basic invocation.

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

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

With 0% schema description coverage, the description compensates well by explaining that experience_id is a stable ID obtained from list_reviews_by_visibility and by clarifying the public visibility's effect on publication_status. The enum values are not individually glossed, but the core meaning of both parameters is 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 clearly states the action ('Change... review'), the exact resource ('one authenticated-user-owned review'), and the specific visibility values. It also names the key identifier type ('stable experience_id'), making the tool's purpose unambiguous and distinguishable from siblings like list_reviews_by_visibility or delete_experience.

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 clear contextual guidance by instructing the agent to first use list_reviews_by_visibility to translate conversational list numbers into stable IDs. It does not explicitly enumerate when not to use this tool or compare it with alternatives, but the prerequisite and ownership constraint give a solid operational context.

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 mutability and idempotency, and the description adds meaningful behavioral context: relationships are editable metadata, they never determine storage IDs, and the server independently validates structural writes so client guidance cannot override. It also instructs preserving disagreement about edge meaning, which is useful non-obvious behavior. No contradiction with annotations found.

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 and example before the nuanced rules. It is longer than strictly necessary for a three-parameter tool, but most sentences earn their place by preventing common semantic errors. The structure is logical: purpose, prerequisite, effect, then classification guidance.

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

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

For a mutation tool with no output schema, the description gives prerequisites, semantic intent, edge-case guidance, and server-side validation behavior, which covers most invocation concerns. It does not specify return values or whether relationship values are restricted to a controlled vocabulary, but the default relationship and example cover the primary path adequately.

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 provides only three bare string fields with 0% description coverage, so the description must compensate. It effectively explains source_type and target_type as 'existing subject types' and the relationship via the example 'ferry belongs_to transportation,' clarifying the directional semantic edge. It also gives rules for what should go into subject types versus attributes, adding real meaning to the values. It could still benefit from explicit definitions of each parameter and allowed relationship values, but it does substantial work beyond the schema.

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

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

The description states a specific action and resource: 'Add editable classification metadata between existing subject types,' with a concrete example ('ferry belongs_to transportation'). It also distinguishes this from naming/identity concerns by stating it is 'a semantic assertion, not a naming choice,' which helps separate it from sibling tools like register_subject_type_alias.

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 explicitly names when a prerequisite applies: 'Unknown types must first be resolved with resolve_subject_hierarchy.' It also provides substantial usage context, including that relationships improve broad search but never determine storage IDs, and offers detailed guidance on when compound subjects should remain distinct types. It does not systematically compare against every sibling, but the essential routing guidance is present.

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

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

Annotations already mark the tool as non-read-only, non-destructive, and idempotent. The description adds meaningful behavior beyond those flags: contributions are immutable, votes are advisory, and the server independently checks machine-verifiable acceptance criteria and referenced review IDs. No contradiction with annotations is present.

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 first defines scope, the second adds vote-specific requirements, and the third adds side effects and server behavior. Important information is front-loaded, and 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 complex 9-parameter mutation with no output schema, the description covers purpose, side effects, vote semantics, and server-side validation. It does not spell out return or error behavior or the exact meaning of idempotency_key deduplication, but the annotations already indicate idempotency and the core invocation context is 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?

Schema description coverage is 0%, so the description must compensate. It explains the vote-specific evidence structure and lists contribution_type values, but it leaves key required fields like deliberation_id, idempotency_key, and content to rely on their names and schema types. It only lightly touches responds_to_contribution_ids via 'referenced review IDs', so coverage is partial.

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

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

The description opens with a specific verb and object: 'Add an immutable proposal, critique, counterproposal, reconciliation or vote.' The enumerated contribution types match the schema enum exactly, so the agent can immediately identify what this tool does and distinguish it from create_deliberation or save_assessment.

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 a vote, including the required evidence shape ('vote=approve|reject|abstain' plus a non-empty reason). It also states that votes are advisory and never resolve a deliberation, implicitly steering agents away from using this tool for resolution. It does not explicitly name sibling alternatives, which keeps it just below a perfect 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, so the safety profile is covered. The description adds genuinely useful non-obvious scope information, such as 'There are no DNS storage paths or review leaf concepts,' and explains that naming disagreement is soft while semantic disagreement may require deliberation. This goes beyond the annotations by clarifying what the index does and does not settle.

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 purpose and the recommended trigger in the first two sentences, which is good structure. However, the later guidance is lengthy and somewhat repetitive, especially the two separate sentences emphasizing that naming disagreement should not block use. The 'server independently validates structural writes' note is also tangential to invoking this read-only index.

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

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

For an empty-input, read-only listing tool, the description covers what it returns, when to call it, and how to interpret the vocabulary semantics. It does not describe a detailed return schema or pagination, but no output schema is provided and the first sentence adequately states the return scope.

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 the schema coverage is trivially 100%, so there is no parameter surface for the description to explain. The description instead adds meaning to the vocabulary content itself, which is the only relevant semantic dimension for an empty-input inspection 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 the tool as a vocabulary-wide inspection endpoint and distinguishes it from siblings like get_subject_classification or resolve_subject_type, which operate on specific subjects rather than the whole standard vocabulary.

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 an explicit trigger: 'Inspect this before classifying any unknown subject type.' This is clear contextual guidance and also implies the tool is a prerequisite before classification-related siblings are used. It does not explicitly name exclusions or alternatives, but the abundant sibling list makes the intended workflow reasonably apparent.

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