TestGraph

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

Adds meaningful behavioral constraints beyond the annotations: coordinates are WGS84 only, coordinates are never silently geocoded, and new Places require canonical plus durable identification. With idempotentHint already present and destructiveHint false, these are the key behaviors an agent needs and they are disclosed.

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

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

Four short sentences contain no filler. The first sentence states the primary purpose and each subsequent sentence adds a necessary rule or constraint.

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

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

The description covers the critical path: resolving subject/Place, supplying source provenance, constructing new Places, and respecting WGS84. But given 11 parameters, no input-schema property descriptions, and no output schema, the agent still lacks enough information about the expected shape of `value`, how `qualifiers` and validity windows work, and what the response will contain.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies source as provenance, object_place's canonical_key and identifiers, and the coordinate encoding for position-like values. However, with 11 parameters it leaves `value`, `qualifiers`, validity fields, and the source object contents largely undefined, forcing the agent to infer from sparse names and enums.

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 action, 'Add', and a specific resource, 'governed location assertion', for an existing eligible subject. This clearly separates it from sibling tools like get_location_assertions and resolve_location_assertion.

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

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

Gives actionable usage guidance: resolve the subject and existing Place first, provide a canonical key plus durable identifier for new Places, and always include source provenance. It does not explicitly name alternatives or state when not to use this tool, but the prerequisites are strong enough for an agent to route correctly.

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

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

The description adds substantial context beyond the annotations: atomicity, idempotency with a named error, the notion of the authenticated client, and the scope limitation that claiming grants no authority outside the deliberation. This is richer than merely relying on the idempotentHint 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?

Three concise sentences, each with a clear job: what the tool does, its idempotency characteristics, and its scope boundary. No filler, and the most important information is front-loaded.

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

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

The behavioral description is strong, but with no output schema and no parameter documentation, the agent is left without critical call-time details: what source_model means, how idempotency_key should be generated, and what a successful claim returns. These gaps are not merely cosmetic; they affect correct invocation.

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

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

Schema description coverage is 0%, and the tool description does not explain any of the three parameters. Repeating a claim being safe suggests idempotency_key’s purpose, but it never connects that to the actual parameter, and deliberation_id and source_model are completely unannotated.

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 precise verb ('claim') with a specific resource ('open deliberation') and adds key constraints: atomicity and the authenticated client. This clearly differentiates it from sibling tools like create_deliberation 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 implies the use case — claiming an open deliberation — and contrasts it with non-claim actions, but it does not explicitly state when to use this tool rather than, say, list_open_deliberations or create_deliberation. No direct exclusions or alternative routing is provided.

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

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

Annotations already communicate destructive and idempotent behavior. The description adds important context: the precondition that the current value must match expected_value, that authoritative evidence and a reason are mandatory, and that the system preserves an immutable correction record in the provenance history. This is meaningful detail beyond what annotations show, though it does not detail side effects such as fanout to downstream indices.

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 fits in three sentences, is front-loaded with the action, and each sentence adds a different, necessary value: what it does, the behavioral preconditions and side effects, and when not to use it. There is no repetition, fluff, or exploration of already-schema-known 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?

Given that there is no output schema, the description provides the critical operational context: when to invoke, what must be present, and the mutable nature via annotation. It does not state what is returned to the caller, but for a correction operation with meaningful validation preconditions, the key invocation factors are covered. A slightly richer description might mention failure modes when the current value does not match expected_value.

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 13%, but the description compensates for several parameters: expected_value must match the current stored value, corrected_value is the replacement, field_root separates identifiers/config vs attributes, and reason/evidence_sources are mandatory authoritative inputs. It does not explain idempotency_key at a semantic level, but the idempotentHint annotation partially covers that concern.

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 actively states a clear verb and resource: 'Replace one incorrect identifier or attribute using the stable subject ID.' This goes beyond the title by specifying the exact unit of work and the scoping constraint (subject ID). It also differentiates the tool from enrich_subject by making clear that this is for correction, not addition.

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

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

It gives explicit when and when-not guidance: use it to replace an existing incorrect value, but 'Use enrich_subject for missing facts; never use this operation merely to add a value.' This provides a closely related alternative and states the exclusion condition directly, so an agent can route decisions effectively.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond them by stating that stored content is advisory and not authority for unrelated external actions, and that a proposal remains inactive until explicit user approval. 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?

Four sentences, each adding value, with the primary purpose front-loaded. The governance configuration is the longest sentence and comes last, preventing it from burying the core meaning. 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?

Given an 8-parameter tool with nested objects and no output schema, the description covers the essential context: identity use, invariability of stored content, governance variant, and activation semantics. A brief statement of what the operation returns would push this higher, but nothing critical is missing for correct invocation and expectation-setting.

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

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

Schema description coverage is only 13%, so the description compensates for the most opaque parameters: it explains the semantics of canonical_key, and the governance-related context fields (governance_kind, guidance_key, guidance_scope, target_model). The remaining parameters are only lightly conveyed, but a one-parameter gap remains.

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 verb-plus-resource relationship: create a private, user-owned question that multiple authenticated MCP clients can examine and answer. This conveys the tool's distinctive purpose and distinguishes it from retrieval or resolution siblings without naming them explicitly.

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

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

The description gives concrete guidance for the canonical_key idempotent use and a fully specified pattern for the induction-guidance scenario. It does not explicitly name alternatives or when to prefer other tools, but it makes the intended usage context 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 substantially enriches the annotations by explaining cascade behavior — dependent AI assessments are deleted — and the conditional deletion of the subject. It also discloses ownership enforcement and explicit user request requirements, which go beyond the destructiveHint 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?

The description is compact and front-loaded with the most important safety constraint. Each sentence delivers distinct value: when deletion is allowed, ownership, dependency effects, subject preservation, and confirmation handling — no filler.

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

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

For a destructive tool with no output schema, the description covers the major decision points: authorization, ownership, side effects, and orphan handling. The main gap is that the parameter semantics for delete_orphan_subject=false and response/error behavior are not fully detailed, though the overall flow is understandable.

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 meaning. It does convey the confirmation requirement and the orphan-subject behavior, but it never names confirm_deletion, idempotency_key, or delete_orphan_subject, and the exact effect of delete_orphan_subject=false is left ambiguous.

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

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

The description is specific and action-oriented: 'Permanently delete one review' names the exact operation and resource. It also distinguishes itself from other review-related tools like save_experience by emphasizing destructive, single-review scope.

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

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

The description clearly says deletion is permitted only after the user explicitly requests it and that no second confirmation should be requested when authorization is present. It does not explicitly name alternative tools, but the conditions for when deletion should occur are unambiguous.

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

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

Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already indicate a safe, idempotent write, and the description extends this materially: it preserves existing conflicting values rather than overwriting them, and it implicitly defines collection behavior (unavailable vs. independent) while clarifying that 'unavailable' cannot be used for size, effort, or inconvenience. This adds actual behavioral nuance beyond the annotation booleans.

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

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

The description is long but densely informative—only a few sentences are generic filler. It front-loads the key claim ('add missing', 'without creating other reviews') and then efficiently enumerates constraints and non-goals. It loses a point because the collection-specific paragraph is longer than needed and could be tightened without losing meaning, but it never repeats the same guidance twice.

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 10 parameters, several nested objects, and no output schema, the description covers the operational context well (how to validate source pages, what to express in retrieval_usages, what counts as complete coverage). It also explains the boundary between 'unavailable', 'independent', and collection membership in prose. Missing: it never explicitly defines what a valid source_manifest looks like for a standalone (non-collection) case, and it could suffice with credit that source_manifest is only required for collection members.

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 40%, and while the description adds important constraints for source_manifest (exhaustive, page mapping, exhaustion_evidence, coverage_status rules) and collection_assessment.unavailable semantics, it leaves identifier/attributes/provenance parameter semantics entirely to the schema. The schema's descriptions for individual fields are helpful where present, but collection_assessment and subject_enrichment_check get the bulk of the behavioral depth; the generic subject fields do 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 title 'Enrich an existing subject' and description state a clear verb ('Add a'), resource ('identifiers, attributes like provenance and credentials to an existing subject'), and explicit scope ('without creating another review'). It clearly distinguishes from siblings like save_object (save), resolve_subject (identity resolution), and search (query-only).

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 states when to use this tool ('when finding a subject was not identified during original processing' and when authoritative info was omitted), and provides strong exclusion guidance: do not use for creating reviews, do not ask for routine lookup permission, and do not store unverified speculation. It also names distinct action paths for collection-based vs. non-collection workflows, routing the agent to specific behaviors (traverse pagination, sitemaps, APIs).

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

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

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

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

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

The description is one short, front-loaded sentence that immediately identifies the resource and its key output components. Every part of the sentence earns its place and there is no redundant filler.

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

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

For a simple one-parameter fetch, the description is sufficient: it identifies the resource, the parameter is clear, the annotations cover safety behavior, and the description states the main returned content. No output schema exists, so the high-level return summary is helpful and acceptable.

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

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

Schema description coverage is 0%, so the description must compensate for the id parameter. It does not: only the field name and format indicate what id represents. The parameter is simple and arguably inferable, but the description adds no semantic meaning beyond the schema.

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

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

The description names a specific resource ('review') and a specific operation ('fetch'), and enumerates what a fetched review includes: stable subject type, original words, and AI assessments. This clearly separates it from the other get_* and search siblings in the tool list.

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

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

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

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

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

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

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

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

The description is compact and well-structured: the first sentence carries the full retrieval purpose and contents, and the second sentence adds an important safety caveat. Every clause adds signal and there is no repetition of what the annotations already say.

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

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

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

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

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

Schema description coverage is 0%, so the description carries the burden. It does add a useful qualifier: canonical_key is 'stable', and it states retrieval is possible by either UUID or canonical_key. However, it does not clarify precedence, mutual exclusivity beyond the schema, or when each key type is more appropriate, so the action compensates only partially.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a simple zero-required-parameter read-only tool with no output schema, the description covers why, when, and how to call it, what it returns, which data is excluded, and how the optional parameter affects the result. An agent has enough to call this correctly without further inference.

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

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

Schema coverage is 100%, so the schema already documents the optional source_model and the maxLength. The description adds practical meaning by explaining that passing source_model enables model-specific approved guidance to be layered over global guidance, going beyond a bare parameter listing.

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

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

The description states a specific verb ('get') and a specific resource ('TestGraph induction and governed guidance'), and clarifies what it returns: server baseline plus user-approved global and model-specific guidance. It is distinct from sibling tools because it focuses on induction/orientation guidance rather than assertions, deliberations, or contributions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With 0% schema description coverage, the description must clarify the parameter, but it only refers to 'one subject' without naming subject_id or explaining its role beyond the obvious property name. It adds minimal value beyond the input schema.

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

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

The description uses a specific verb ('Return') and identifies the exact resource: all visible location assertions for one subject. It also lists included content (provenance, conflict state, Place identity, migration drift), which clearly separates it from sibling tools like get_deliberation or resolve_location_assertion.

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

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

The description states what the tool does but gives no explicit guidance on when to use it versus alternatives, no exclusions, and no mention of alternative tools. An agent must infer that it is the query tool for location assertions rather than being told.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description needs only add value beyond those. It adds useful scoping ('this user's' open work) and alias semantics, but it does not disclose return format, pagination, or ordering behavior. This is acceptable but not rich.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives concrete usage context: use it for discovery without identifiers, and use target_model plus unclaimed_only to filter before claiming a task. It does not explicitly name sibling alternatives or say when not to use it, but the intended workflow is clear and actionable.

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

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

Beyond the annotations, the description reveals meaningful behavioral side effects: it records accepted contributions and unresolved points, requires user_approved=true, and for induction-guidance deliberations, a successful resolution becomes active guidance returned by get_induction. The AI-vote limitation is also explicitly disclosed, which is valuable for safe invocation.

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 carry all essential information without filler. The first sentence names the action and the second adds critical conditional behavior and integration context. Every sentence earns its place.

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

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

The description is rich and covers the main correctness drivers, including the activation side effect in get_induction. The only notable absence is an explicit statement about the return value on successful resolution or failure handling when user_approved=false. With no output schema, this minor gap remains.

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

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

The input schema has no property descriptions, so the description compensates by explaining the core semantic parameters: 'accepted contributions' maps to accepted_contribution_ids, 'remaining disagreement' maps to unresolved_points, and it explicitly states that user_approved must be true. It does not clarify idempotency_key or rationale in detail, but the parameter names and constraints are relatively self-explanatory.

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

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

The description clearly states a specific verb, resource, and purpose: 'Close a deliberation with the user's explicit decision.' It also disambiguates the action from consensus inference, AI-vote recording, and contribution submission, which distinguishes it from siblings like create_deliberation and submit_contribution.

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

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

It explicitly conveys when the tool is appropriate: when a user has approved a resolution and the deliberation should be closed. It also states a key when-not: AI votes alone have no activation authority and consensus is not inferred. It does not name a specific alternative tool, so it lacks fully explicit routing to an alternative sibling.

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 communicate mutation (not read-only) and idempotence, so the bar is lower. The description adds useful behavioral context about global canonicality and automatic attachment of existing fields, but it doesn't disclose side effects or consequences of registering a globally visible field, such as visibility, manual, not reversible, etc.

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

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

The description is three compact sentences with no filler, and each one earns its place: the first defines the tool, the second imports a clear checking policy, and the third steers toward an alternative. The most important purpose statement 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?

The description is complete at the decision level, explaining when to register and what not to confirm, and the annotations cover safety and idempotence. However, given nested parameters and 0% schema coverage, the lack of any guidance about json_schema or aliases leaves notable gaps for correct invocation as a generic global field.

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

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

Schema description coverage is 0%, so the description has the burden of explaining parameters. It only touches canonical_name and subject_types implicitly; aliases, description, and particularly json_schema — a nested object parameter—are left entirely unspecified, which weakens an agent's ability to construct a 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 first sentence states the exact purpose with a specific verb and resource: register a genuinely new globally canonical field or explicitly pre-attach one to subject types. This distinguishes it from relevant siblings like register_subject_type_alias and makes the tool's placement in the workflow obvious.

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 usable guidance contrary to conservative behavior: do not ask for routine confirmation to reuse an existing canonical field, and prefer raw_text for one-off narrative detail. It falls slightly short of full marks because it doesn't explicitly name a sibling candidate for field registration or state the exact condition under which the tool should or shouldn't be called.

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 explains that registering an alias does not require other AIs to prefer the same name and that wording disagreement is not a semantic conflict. This adds meaningful contextual behavior, while the side-effect details are partially covered by idempotentHint and destructiveHint.

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 concise and front-loaded with the core purpose in the first sentence. The remaining sentences earn their place by clarifying exclusions and the semantic model of aliases, though the final sentence is slightly nuanced.

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 simple two-string schema, idempotentHint, and no output schema, the description provides enough context for an agent to invoke the tool correctly. It covers the relevant semantic constraints and distinguishes the operation from category relationships.

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 provide meaning beyond the parameter names. It does relate 'alias' to a 'genuinely equivalent expression' and 'subject_type' to an 'existing stable subject type', which helps, but it does not detail constraints such as expected format, uniqueness, or how existing aliases are handled.

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 a specific verb and resource: mapping an equivalent expression to an existing stable subject type as an alias. It also explicitly excludes category relationships, which separates it from sibling tools like set_type_relationship, though it does not name a sibling directly.

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

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

The description gives explicit usage direction: use this for genuine naming equivalence, never for a category relationship. It also explains a key behavioral boundary—disagreement about wording alone is not a semantic conflict—so an agent knows when this tool is appropriate.

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

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

The description adds one meaningful behavioral fact beyond the annotations: the submitting client cannot resolve its own contested claim without explicit user approval. Annotations already state that the operation is not read-only but idempotent and not destructive, and the description does not contradict that. It does not go into detail about what accepting versus rejecting does to the assertion or what the operation returns.

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

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

The description is short and front-loaded: the first sentence states the core purpose directly, and the second sentence adds a useful authorization constraint. There is no filler, but there is room to include a sentence about idempotency/effect without sacrificing this efficiency.

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 five parameters, no output schema, and no per-parameter docs, the description leaves significant ground uncovered: what happens after a decision, whether the operation has side effects beyond the resolution, and how idempotency_key behaves. While the approval context is helpful, a state-changing tool with this many required fields normally needs more guidance than a concrete list of preconditions and alternatives.

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 no per-property descriptions (0% coverage), and the description does not compensate for the low coverage. It only hints at the user_approved concept via 'explicit user approval' and at the contested nature of the assertion, without explaining assertion_id, rationale, decision, or idempotency_key. The parameter names and enum carry most of the meaning.

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/action ('Accept or reject') and a specific resource ('a contested location assertion'), so an agent can tell this is a decision operation from the name and title. It does not explicitly contrast itself with siblings like record_resolution or get_location_assertions, but the 'contested' framing and the accept/reject pair make the core purpose 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 useful context about when resolution is allowed: the submitting client cannot resolve its own contested claim without explicit user approval. It does not explicitly say when to choose this tool over alternatives such as assert_location or record_resolution, nor does it state success criteria for using it.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the annotations, the description discloses important behavioral details: existing dictionary entries are reused, only missing provisional nodes are created, cycles are rejected, and semantic placement must never be determined by review arrival order. It also explains how naming variants are treated, which goes well beyond the structured metadata.

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 appropriately sized for the complexity of the operation and every sentence contributes decision-relevant information. It front-loads the precondition and broad-to-specific ordering before moving to important exclusions and semantic caveats.

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

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

For a one-parameter configuration with no nested objects but a high set of semantic exceptions, the description conveys it: ordering, preconditions, exclusions, side effects, cycle rejection, and reuse behavior. It is complete enough for an agent to invoke it correctly without needing to consult a more detailed return contract.

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

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

With 0% schema description coverage, the description does the heavy lifting for the 'terms' parameter. It explains that terms must be submitted broad-to-specific, gives a concrete example, and clarifies that terms can map to existing concepts or new provisional nodes depending on semantic intent. This is exactly the parameter guidance that the schema itself does not provide.

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 says the tool 'resolves' a 'semantic subject hierarchy' and details what happens: reuse existing entries, create missing provisional nodes, add belongs_to relationships, and reject cycles. It also distinguishes itself from vocabulary_index by stating it should be used after vocabulary_index when the specific subject type does not yet exist.

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 text gives an explicit when-to-use condition ('Use after vocabulary_index when the specific subject type does not yet exist'), an explicit exclusion ('Do not include review'), and concrete semantic rules for when to reuse identity versus create a new node. This is unusually strong guidance for choosing this tool over semantic alternatives.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the annotations, the description reveals critical consequences: the relationship becomes a 'rejection tombstone' and 'another AI cannot silently recreate it.' This adds meaningful behavioral context about durability and side effects that the raw annotations do not communicate.

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

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

Two dense sentences carry both the core action and the key consequence. No filler is present, and the most important scope information is front-loaded.

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

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

The description covers important consequences of retirement but omits parameter explanation and return behavior. Since there is no output schema and low schema coverage, this leaves the overall call contract under-specified; however, the description's tombstone and preservation details make it minimally viable.

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 is responsible for clarifying the parameters. It only refers vaguely to 'one exact semantic relationship' and does not explain source_type, target_type, relationship, or reason. The agent is left to infer the meaning and makeup of required arguments.

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

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

The description uses a specific verb and resource: 'Retire one exact semantic relationship' while preserving subject type, subjects, and reviews. This clearly distinguishes retirement from deletion and from creating relationships, aligning with the sibling tool set_type_relationship without needing to name it.

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 context of 'incorrect subject classification' implies when this tool should be used, but there is no explicit when-to-use or when-not-to-use guidance, nor any comparison to alternatives like set_type_relationship. It is usable but leaves the agent to infer boundaries.

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 idempotentHint=true, but the description extends that by explaining how to derive deterministic idempotency keys and that retries and restarted conversations should return existing writes. It also states the attribution/association semantics. This is meaningful behavior beyond what annotations alone convey.

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

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

The description is concise and front-loaded with the purpose, then adds focused operational guidance on batching and idempotency. All sentences serve a purpose, though the final sentence is long and could be split for readability.

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 concurrency, batching, and idempotency well, and it references association with a review. However, with no output schema and low parameter coverage, it leaves gaps about the meaning of review, assessment_type, and return behavior, making it only partially complete for a 8-parameter mutation tool.

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

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

Schema description coverage is 0% and there are 8 populated parameters, so the description must compensate. It only adds detail about idempotency_key derivation; it does not explain experience_id, assessment_type, analysis, evidence, conclusion, or confidence meanings, leaving the agent to infer those semantics.

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

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

The description states a specific action (save), a resource (AI-derived assessment), and a constraint (against the exact review it evaluates). This is clear enough on its own, but it does not explicitly distinguish this tool from sibling save_experience or submit_contribution, so it does not earn 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 provides concrete operational guidance: batch independent writes as multiple tool calls up to 10, and do not batch dependent operations until prerequisites are confirmed. It does not clearly state when an agent should choose save_assessment over alternatives like save_experience or submit_contribution.

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?

This is far more behaviorally open than annotations require. It explains retry-and-scope discipline, idempotency behavior, server-side verification of collection membership, coverage_status semantics, default experience date behavior, the prohibition on silent geocoding, and the condition that incomplete manifests are rejected. It also clarifies that enrichment is shared graph-building work. No contradiction with the annotations was 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 first sentence is a sharp, useful front-loaded purpose statement, but the description becomes a long unbroken block and repeats core ideas multiple times, e.g., the same 'register something someone would search for later' and 'shared graph building' concept appears several times. Although there is a lot of genuinely useful material, it is not concise and the redundancy makes it harder to process.

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 17-parameter nested tool with no output shape and low schema coverage, the description is unusually complete: it covers the collection-workflow lifecycle, idempotency, enrichment alignment, and server expectations. It still leaves some simple fields such as user_approved, visibility, and headline behavior unspecified, but those are less likely to cause missuse, while the hard parts of this tool are thoroughly covered.

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 about 18%, and the description carries a heavy load of parameter-level detail through phrases like 'submit the result in subject_enrichment_check', 'reuse the collection_id and manifest_revision', 'include reviewed_subject in submitted_member_refs', and 'store the canonical URL in identifiers'. It also gives precise semantics for applied_fields, retrieval_uses, unapplied_sources, coverage_status, and idempotency_key, which is exactly what is needed given the low schema coverage.

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

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

The description begins with a specific action and target: 'Save a review against an already-resolved stable subject type.' The title and first line also establish that this is the save-and-review workflow, not a resolution, enrichment, or assessment tool. Its scope and conditions are concrete enough to separate it from related tools such as save_assessment and submit_contribution.

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

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

The description gives extensive when-to-use context: it applies to any kind of subject, does not require website/location/address/relationship, and tells the agent to auto-retry. It does not explicitly name alternative tools or conditions for selecting a sibling tool, so it falls short of top-level exclusion guidance, but within its own workflow the usage conditions are clearly specified.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It gives explicit workflow instructions: try one keyword at a time, follow up with exact subject-name searches, paginate using cursor until complete, and fetch each returned review before answering. It also provides when-not-to-stop guidance for location queries and says partial or unknown coverage must be reported as uncertainty, which is strong usage guidance.

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

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

Annotations already indicate idempotent, non-read-only, non-destructive behavior; the description adds meaningful behavioral context: the metadata is editable, affects search only, never determines storage IDs, and is a semantic assertion. The explicit instruction to preserve disagreement between independent AIs rather than treating alternate labels as proof is valuable beyond the structured metadata and does not contradict 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 definition is front-loaded with the main purpose and backed by only high-value caveats. All sentences contribute something: an example, a prerequisite, scope, semantic meaning, and disagreement handling. It is slightly philosophical in the final sentence, but the guardrail is relevant to the tool's purpose.

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 three parameters, no enums, no nested objects, and no output schema, the description captures the essence of what the tool does, what inputs are expected, what its limitations are, and how it should be used with resolve_subject_hierarchy. It does not specify overwrite behavior or error cases, but the idempotent annotation partially covers that.

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, so the description must compensate. It does by providing the example that maps source_type, target_type, and relationship, and by stating that the types must already exist and unknown types must first be resolved. It does not list all valid relationship values or exact identifier formatting, but it gives enough semantic grounding for use.

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 in the first sentence: 'Add editable classification metadata between existing subject types.' It gives a concrete ferry/transportation example and reinforces that this is a semantic assertion, not a naming choice, which distinguishes it from alias, resolution, and sibling relationship tools.

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

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

It explicitly names the precondition to resolve unknown types using resolve_subject_hierarchy and clarifies when relationships matter (broad search) and when they do not (storage IDs). It does not exhaustively discuss alternatives like retire_type_relationship or register_subject_type_alias, but the guidance is strong enough for an agent to select this tool correctly.

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

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

Beyond the annotations, the description discloses meaningful behavioral detail: contributions are immutable, votes do not resolve deliberations, attribution and disagreement are preserved, and the server independently validates both machine-verifiable acceptance criteria and referenced review IDs. There is no contradiction with the provided annotations; the description adds essential operational context that is neither obvious from the flags nor from the schema alone.

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

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

The description is compact, well-organized, and starts with the decisive fact: 'Add an immutable proposition, critique, counterproposal, reconciliation or vote.' The subsequent sentences earn their place by adding vote-specific requirements and wording about server-side validation. There is no filler and no repetition of information already present in the schema.

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

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

Given the complexity of the tool, the description covers the most important behavioral and validation information: mutability, vote semantics, attribution, acceptance, and validation of referenced records. It falls short only in that some parameter semantics remain opaque and the response or success/failure shape is not mentioned, though no output schema is provided. Overall, the contextual contract is strong but not exhaustive.

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?

Because schema description coverage is 0%, the description must compensate for every parameter's semantics. It does add critical guidance for the evidence object when contribution_type is 'vote' and mentions that referenced review IDs are checked. However, it does not explain the required idempotency_key behavior, or provide sufficient clarification for optional fields such as confidence, source_model, unresolved_points, or responds_to_contribution_ids. With the schema itself bare and no description for these fields, this is 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 clearly identifies the action ('Add'), the exact resource (a contribution to a deliberation), and enumerates the accepted contribution types: proposal, critique, counterproposal, reconciliation, or vote. The inclusion of 'immutable' and 'attributed' narrows the semantic scope beyond the title alone and differentiates the operation from sibling tools like create_deliberation or record_resolution.

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

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

The description communicates that this tool is for additive contribution submission, not for resolving a deliberation or triggering guidance, since votes are explicitly advisory. However, it does not name a preferred alternative tool, such as record_resolution, for finalizing an outcome, so the when-not-to-use guidance is direct but alternatives are left to inference.

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

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

Annotations already carry readOnly and non-destructive hints. The description adds meaningful behavioral context: naming disagreement must not block standard adoption, unrelated labels may alias to the same identity, and semantic disagreements may require deliberation or separate concepts. This significantly prevents misuse beyond what annotations alone convey.

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

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

The tool's main purpose and usage are front-loaded in the first two sentences. Later sentences expand on alias/disagreement behavior in a logically organized way, though a few phrases like 'review leaf concepts' are less crisp and slightly obscure the otherwise good structure.

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

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

Given the tool is a read-only inspection with zero parameters and no output schema, the description provides enough context about what is listed and how to interpret vocabulary disagreements. It could be slightly richer about output shape or the meaning of 'flexible relationships' but is still competent.

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 properties, so all parameter semantics are already inherently complete. The description does not need to cover parameter details, and the content list adds background rather than conflicting with schema coverage.

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

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

The description opens with a specific verb and resource: 'List canonical subject types, aliases, flexible relationships and reusable fields.' This clearly differentiates the tool from siblings such as resolve_subject or register_subject_type_alias and matches the title while adding concrete output scope.

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

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

The description gives explicit when-to-use guidance: 'Inspect this before classifying any unknown subject type.' It also warns against blocking naming disagreements and against collapsing semantic disagreements. However, it does not explicitly name alternative tools or state when-not-to-use beyond the implicit classification context.

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