TestGraph

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

Annotations already signal readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description only needs to add behavioral context beyond that. It does exactly that by noting coordinates are WGS84-only, never silently geocoded, and that new Places need canonical keys and durable identifiers. These are meaningful expectations not derivable from the annotations 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 exactly three sentences and every sentence earns its place. It front-loads the core action, then gives prerequisites, special case handling, source requirements, and an important geocoding constraint, all without 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?

The tool has a fairly complex schema with nested objects, optional values, and varied predicate semantics. The description covers the high-level workflow and safety constraints well, but it does not explain the relationship between predicate, value, and object_place. That leaves room for incorrect invocation when trying to decide whether a location is passed as a Place object, an identifier, or coordinate data.

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?

Since schema coverage is 0%, the description carries real responsibility and it does add meaning for subject_id, object_place, source, and coordinate-like values. However, it still leaves a number of parameters semantically unexplained, particularly value, qualifiers, visibility, valid_from, valid_to, and observed_at. The guidance is helpful, but it does not fully compensate for zero schema descriptions across 11 parameters.

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

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

The description opens with a specific verb and resource: "Add a governed location assertion for an existing eligible subject." This clearly distinguishes the tool from siblings like resolve_location_assertion, get_location_assertions, or delete_experience, and the rest of the description reinforces what makes this specific assertion governed.

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 important usage prerequisites: resolve the subject and any existing Place first, and provide source provenance. It also states the special condition for New Places. It does not explicitly say when not to use the tool or name alternative tools, so it stops short of a full when/when-not comparator.

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

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

The description goes beyond the annotations by disclosing atomicity, idempotent retry semantics, the exact `DELIBERATION_ALREADY_CLAIMED` failure condition for other clients, and the scoping statement that claiming grants no authority outside the stored deliberation scope. All of this is consistent with `idempotentHint=true`.

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 uses three compact, information-dense sentences with no filler. The primary action is front-loaded, and each sentence adds distinct value: atomic behavior, conflict/idempotency semantics, and scope limitation.

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 atomicity, conflict resolution, idempotency, and authorization scope, which is a strong base for invocation. The remaining gaps are the meaning of `source_model` and the lack of any return-value explanation in the absence of an output schema, but the core claim behavior is clear enough.

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 must make the parameters understandable. It never names `idempotency_key` or explains `source_model`, and the idempotency semantics are only implied by the phrase 'Repeating the same claim is safe'. An agent can infer `deliberation_id` from the tool name and schema, but the optional parameter remains opaque.

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 action ('Atomically claim'), a specific resource ('an open deliberation'), and a specific owner ('the authenticated MCP client'). It also adds the error case for conflict, which separates claiming from simple creation or retrieval tools such as `create_deliberation` and `get_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 implies the intended workflow of claiming a deliberation before working on it, but it never references siblings like `list_open_deliberations` or `get_deliberation` to say when each is appropriate. It provides strong operational caveats, but no explicit when-to-use or when-not-to-use guidance.

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

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

Beyond the annotations, the description discloses that the operation replaces an existing value, requires authoritative evidence and a reason, requires expected_value to match the current value, and preserves an immutable correction record in subject provenance. This is useful behavioral context that the annotations alone do not provide, and there is no contradiction.

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

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

The description is compact and front-loads the core action, then adds the necessary constraints and the forbidden usage. Every sentence is substantive, and there is no unnecessary repetition of schema-visible facts.

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-required-parameter destructive operation with no output schema, the description covers the core invocation context, includes a useful alternative tool, and gives important behavioral constraints. However, it leaves minor but relevant gaps: what happens when expected_value does not match, idempotency-key semantics, and how corrected_value should be shaped relative to field_root.

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 needs to compensate. It clarifies subject_id, expected_value matching the current value, and the mandatory nature of evidence and reason, but it leaves idempotency_key, corrected_value, and the field_root/field_path navigation underdescribed. The schema still bears most of the responsibility for those parameters.

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

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

The description states a specific action verb ('Replace'), a clear scope (one identifier or attribute value), and the stable subject ID. It also differentiates from enrich_subject, which is for adding missing facts, so the agent can distinguish this tool from its main sibling without opening the schema.

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

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

It is explicit about when to use this tool and when not to: use enrich_subject for missing facts and never use this operation merely to add a value. The precondition that the current value must match expected_value also gives a clear correctness guard for invocation.

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

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

The annotations already declare idempotent, read-only, non-destructive; the description adds meaningful behavior beyond those: stored content is 'advisory... not authority for unrelated disposition', the proposal 'remains inactive until explicit user approval', and the deliberation is described. There is no contradiction with 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?

Three dense sentences (~95 words) with the core purpose front-loaded and the niche inductive-guidance recipe in a single conditional sentence at the end. Every clause earns its place; 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?

The main flow and the special governance-proposal flow are both explained, and idempotency is supported by both the annotation and a required idempotency_key. However, with no output schema, there is no mention of what the tool returns (e.g., a confirmation or the canonical_key to use) nor error/permission behavior, and with 8 parameters including nested objects this is a moderate gap.

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

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

Schema description coverage is only 13% (1 of 8 params documented), so the description carries much of the burden. It adds real meaning for canonical_key ('so another model can retrieve it') and for the context.* fields used in the induction-guidance scenario, which matters because context allows arbitrary properties. But idempotency_key, constraints, acceptance_criteria, and question/title semantics receive no added explanation, leaving the large coverage gap only partially compensated.

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

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

The description states a clear verb+resource: 'Create a private, user-owned question that multiple authenticated MCP clients can examine and answer.' This distinguishes the creation tool from the retrieval, claim, and resolution siblings, and the canonical_key note ties it to later retrieval. It stops short of 5 because it names no sibling explicitly or says what it is not.

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 instructions: 'Use a stable canonical_key so another model can retrieve it' and a precise, scenario-specific recipe for proposing induction-guidance changes with exact field names and values. It does not say when to avoid this tool or name alternatives like claim_deliberation or list_open_deliberations, but the usage context is otherwise 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 significantly expands on the destructiveHint annotation by explaining the cascade: dependent AI assessments are deleted, and the subject is deleted only under precise conditions. This tells an agent exactly which side-effects will happen, which is crucial for a destructive operation. 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?

Every sentence adds a distinct piece of information: the operation, the authorization gate, server ownership, cascade behaviour, subject deletion condition, and the confirmation rule. It is dense but directly relevant, with no filler or repetition.

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

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

The description is thorough for a destructive tool with a small number of parameters: it covers the core side-effects and guardrails. However, there is no output schema and the description does not state what the tool returns (e.g. success or the deleted entity), which leaves a small gap for an agent deciding what to do next.

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 the schema has zero descriptions, the description genuinely compensates: it explains that id identifies 'one review', confirms the meaning and use of confirm_deletion, and details delete_orphan_subject. The missing piece is idempotency_key, which is annotated as idempotent but never explained in text, so not a full score.

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 'Permanently delete one review', giving a specific verb, object, and scope. It also clarifies 'user-owned' and distinguishes from any bulk-delete or save-style sibling tools. The resource and boundaries 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?

It states when deletion is allowed with 'only after the authenticated user explicitly requests deletion' and that ownership is enforced by the server. It also gives an explicit when-not behaviour: do not ask for confirmation when the current request already explicitly authorizes deletion. No alternative tools are mentioned, but no sibling is a delete operation.

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

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

The description adds substantial behavior beyond the annotations: deterministic idempotency keys for retries, batch concurrency up to 10, preservation of conflicting values, collection traversal obligations, and source_manifest reporting. This complements the idempotentHint and destructiveHint annotations rather than simply repeating them.

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

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

The description is long and dense, but the tool is genuinely complex with nested schemas and many behavioral mandates. It is front-loaded with the core action and then works through usage boundaries, collection handling, and concurrency; a more compact version might lose necessary constraint 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 the tool's complexity, the lack of an output schema, and the many edge cases, the description is remarkably thorough. It covers idempotency, retries, concurrency, conflict handling, collection discovery, source_exhaustion, and the retrieval-purpose policy, leaving no major operational gap.

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

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

Schema description coverage is only 40%, so the description must compensate, and it does: it explains idempotency_key derivation, canonical_key reuse, retrieval_uses obligations, source_manifest mappings, and collection assessment behavior. It still leaves some detailed per-field semantics to the schema, but the core parameter intent is well covered.

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

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

The description states a concrete action with a precise target: 'enrich an existing subject' by adding identifiers, attributes, provenance, and related unreviewed subjects. It explicitly excludes creating another review and clearly distinguishes this from sibling tools like correct_subject_fact or save_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 gives explicit when-to-use guidance ('Use this proactively when authoritative information was missed during the original save') and strong when-not signals (do not ask routine permission, do not store merely available facts, do not omit collection members). It does not explicitly name sibling alternatives, though the intended boundary is reasonably 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 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 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?

The description goes well beyond annotations by describing meaningful side effects: records accepted contributions and unresolved disagreement, does not infer consensus, requires user_approved=true, and for induction-guidance deliberations a successful resolution becomes active guidance returned by get_induction. This is substantial forward behavior with no contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds essential behavioral context. It effectively differentiates critical constraints, including the user approval requirement and the exclusive guidance activation effect.

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

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

For a mutating tool with no output schema, the description includes key side effects and conditional activation behavior. A small gap remains: it does not explain what happens when user_approved=false, nor the idempotency_key reason, but the main behavior is adequately 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?

Schema description coverage is 0%, so the description partially compensates by mapping user_approved, accepted contributions, and remaining disagreement to schema concepts. However, idempotency_key semantics, the role of deliberation_id, and rationale are not explained.

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

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

The description opens with a specific verb and resource: 'Close a deliberation with the user's explicit decision.' It further distinguishes the tool from generic deliberation tools by stating that it records accepted contributions and remaining disagreement, requires user_approved=true, and does not infer consensus.

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: use it only when there is an explicit user decision and user_approved=true. It also explains that AI votes alone have no activation authority and that the tool does not infer consensus. It does not name alternative tools explicitly, so no explicit 'use X instead' routing.

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

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

Annotations already signal that the operation is not read-only, not destructive, and is idempotent. The description adds useful context by saying an existing canonical field is attached automatically on first use, which clarifies the idempotency behavior. It does not, however, disclose the broader consequences such as global propagation of the field or whether a registration can be undone.

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, front-loaded, and every sentence carries distinct guidance. The only mild issue is the mention of 'raw_text', which is not otherwise defined in the schema or the input schema, so it may confuse agents looking for a matching parameter or tool.

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

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

Given a 5-parameter tool with no parameter descriptions, no output schema, and nested objects, the description is too sparse. It provides a high-level purpose and usage rule, but not enough detail for an agent to confidently construct a valid register_field call, especially for json_schema and subject_types.

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

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

Schema description coverage is 0%, and the description carries the full burden for explaining 5 parameters, but it does not genuinely explain them. It references 'canonical' and 'subject types' and 'raw_text', but it says nothing about canonical_name conventions, json_schema structure, aliases, or description semantics. The agent cannot reliably populate the parameters from this description alone.

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 operation: 'Register a genuinely new globally canonical field, or explicitly pre-attach one to subject types.' This makes clear both the verb and the resource, and it separates the tool from more general registry or alias tools. It does not explicitly name a sibling tool to contrast with, but the wording is specific enough to be actionable.

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 practical guidance: use it for genuinely new canonical fields or explicit pre-attachment, do not ask for routine confirmation when reusing an existing field, and prefer raw_text for one-off narrative detail. These conditions are clear even though it does not name sibling tools or list all situations where this tool should not be used.

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

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

The annotations already disclose idempotency and non-destructiveness, and the description adds useful behavioral nuance: registering an alias does not require other AIs to prefer the same name, and disagreement about wording alone is not a semantic conflict. This clarifies the expected impact of registration beyond what the annotations 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 short sentences, each earns its place: the first states the action, the second gives the boundary, and the third explains the conceptual implication. No filler or repetition, and the key term 'genuine equivalence' is front-loaded.

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

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

For a two-string-parameter tool with idempotence and destructiveness already annotated over schema, the description fully covers the operation's purpose, its key semantic boundary, and the behavioral consequence. It is complete enough for an LLM or agent to know when and why to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It implies that 'alias' is the equivalent expression and 'subject_type' is the existing stable target, which is enough for basic invocation, but it does not describe string constraints, uniqueness expectations, or what happens if the alias already exists.

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 ('Map'/'Register') against a specific resource ('alias' to 'existing stable subject type') and immediately conditions the operation on genuine naming equivalence. It explicitly distinguishes the tool from category-relationship tools, so an agent can tell it apart from siblings like set_type_relationship.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Use this for genuine naming equivalence' and 'Never use this to express a category relationship.' It does not name the sibling tools that should be used in the category-relationship case, which would make the guidance fully actionable.

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

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

Annotations already cover idempotency and non-destructiveness, so the bar is relatively low. The description adds meaningful behavior beyond annotations by disclosing a key approval constraint: the submitting client cannot resolve its own contested claim without explicit user approval. It does not mention outcome/lifecycle details, but the core behavioral trait 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?

Two sentences with no wasted words; the core operation is front-loaded and the approval constraint is stated immediately after. 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 the purpose and required invocation, the description is largely sufficient: it gives the action, the target object, and the critical user-approval condition. It does not describe the post-resolution workflow or how the result is surfaced, and there is no output schema, but this is adequate for making the call correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'decision' and 'user_approved', but leaves 'rationale' and 'idempotency_key' to inference from their names and schema constraints. This is workable, but not fully compensating for missing schema documentation.

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

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

The description states a specific action ('accept or reject') against a specific resource ('contested location assertion'). This is precise enough for an agent to distinguish it from generic resolution tools and sibling assertion/deliberation tools.

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

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

The description gives clear contextual guidance: use this for contested location assertions, and it explicitly warns that the submitting client cannot resolve its own claim without explicit user approval. It stops short of naming sibling alternatives or explicit when-not conditions, but the context 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 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 transparently explains significant behaviors beyond the annotations: it creates provisional nodes, adds belongs_to relationships, reuses existing dictionary entries, and rejects cycles. It also prohibits placement decisions based on review arrival order. This goes well beyond what the annotations or schema reveal.

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 frontline 'Use after vocabulary_index' immediately tells an agent when to consider this tool. The remaining sentences each add a distinct and necessary piece of behavioral or semantic guidance without unnecessary 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?

Given a single required parameter, no very good output schema, and no output schema, the description is complete enough to invoke correctly. It covers ordering, side effects, special cases, when to use, and the key semantic boundary between naming variants and genuine new concepts.

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

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

There is no parameter description in the schema, but the description compensates thoroughly. It specifies ordering (broad-to-specific), provides an example, forbids the 'review' term, and explains when to reuse existing identity vs. when a genuinely different concept can be added.

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 what the tool does: it resolves a semantic subject hierarchy by submitting broad-to-specific terms, reusing existing dictionary entries, creating only missing provisional nodes, and adding relationships. It also distinguishes itself by saying it is used after vocabulary_index and specifically when the 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 description gives explicit when-to-use guidance: 'after vocabulary_index when the specific subject type does not yet exist.' It also provides exclusions such as 'Do not include review' and instructions about naming variants vs. genuine meaning differences. However, it does not directly name or contrast alternative sibling tools, so it falls 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 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 indicate destructive and idempotent behavior, and the description adds genuine context by saying the relationship is preserved together with subject type and reviews, while the retired edge becomes a rejection tombstone. This gives useful behavioral details about the point of no silent recreation.

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, front-loads the action, and contains no filler. Each sentence contributes necessary info: what is retired and what preserves or behaves afterwards.

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-ish mutation tool with no output schema and little parameter documentation, the description is not clearly complete. It covers the core behavior and persistence semantics, but it does not address retry behavior, success indicators, or the exact meaning of all required 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%, and the description does not explain the source_type, target_type, reason, or relationship parameters. The phrase 'semantic relationship' signals that source and target type exist, but no detail is added about parameter roles, requirements, or the meaning of the relationship default.

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, 'Retire one exact semantic relationship', and names the resource it acts on without ambiguity. It also clearly differentiates from the sibling set_type_relationship by being the retirement/correction path rather than the creation path.

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 title provides a clear implicit cue that this is for retiring an incorrect subject classification, but the description does not explicitly state when to prefer it over alternatives or when not to use it. It gives context for use but no exclusions or direct comparisons to siblings.

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

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

Annotations already declare idempotent, non-read-only, and non-destructive. The description goes beyond these by clarifying that retrles and restarted conversations return existing writes rather mk"duplicating, and by warning not to batch dependent operations until prerequisites are confirmed. It does not disclose return shape or error behavior, but the annotation coverage lowers the bar and idempotent behavior is honestly described.

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 explanation is semicolons-comma run-on but, every sentence advances tool usage: purpose, batch behavior, sequencing constraint, and idempotency guidance. It is somewhat long for a simple save operation but does not contain filler or tautology.

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 adequately covers concurrency behavior and the idempotent retry contract, and the schema handles field names and mandatory properties. It does not, however, define assessment_type values or clarify how analysis/evidence/conclusion relate to idempotency and canonical keys, so an agent cannot be fully confident about what to populate in all cases. No output schema exists, so a brief note on what is being returned would have improved 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?

There is no schema-level description coverage (0%), so the description must carry the burden for explaining the 8 parameters. It adds meaningful guidance for idempotency_key and intgenerates that experience_id references the review being evaluated, but the meaning of assessment_type, analysis, evidence, confidence, and source_model is left to inference. This is insufficient compensation for the lack of structured param 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?

Description states a specific verb and resource: saving an AI-derived assessment against the exact review it evaluates. The phrase 'separately attributed, AI analysis' gives enough identity to distinguish it from broader siblings like save_experience or submit_contribution, though it does not name these alternatives 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?

It implies appropriate usage: this tool is for attaching AI-produced analysis to the relevant review, and the concurrent-batching caveat disposes how to call it. However, it does not explicitly state when not to use it or direct the agent to an alternative sibling for other cases.

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

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

The description massively exceeds the sparse annotations (readOnly=false, idempotentHint=true): it discloses server-side verification of collection membership, manifest reuse semantics, deterministic idempotency across retries and restarted conversations, the complete/partial coverage rule, concurrency batching rules, and the 'never invent or silently geocode' location constraints. All contributed behavior is disclosed before the call is made, with no contradictions against 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 a single ~700-word unbroken paragraph with no structure. It repeats core doctrine (shared-graph building, worth of a realistic future search, non-empty retrieval_uses purpose) multiple times, and includes a low-information marketing sentence about being 'TestGraph's open-ended semantic and discovery engine'. The density and redundancy make streaming parsing harder, even though the content is individually valuable.

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 of very high complexity (17 parameters, 10 required, deep nested objects, no output schema), the description covers most failure modes and invariants: what makes a save valid, when it is blocked (ambiguous), verification vs. coverage status, the first discovery vs. later reuse branch, and proper batch/idempotency behavior. The main gap is return value semantics—the agent has to figure out what the call returns besides the mentioned collection_id/manifest_revision/verification outcomes.

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

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

The description compensates for the very low 18% schema coverage by thoroughly explaining the highest-complexity parameters: subject_enrichment_check statuses with required fields, collection_assessment statuses plus the collection_id/manifest_revision reuse flow and source_manifest invariants, idempotency_key determinism, canonical_key reuse, experienced_at defaults, and rating preservation in structured_data over raw_text. Straightforward parameters like headline, summary, and visibility are left to the schema, but the parameters that actually carry domain risk are given substantial added 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 opening clause states a specific verb+resource: 'Save a review against an already-resolved stable subject type.' The title reinforces it. However, the description never names sibling tools like enrich_subject, save_assessment, or submit_contribution, so the agent must infer how this save differs from them; the remainder of the text is dominated by enrichment and collection policy rather than core purpose.

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

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

There is strong internal workflow guidance: retry automatically, ask the user only when identity is ambiguous, use unavailable/not_applicable statuses with specific reasons, and reuse collection manifests on later reviews. But there is no explicit when-to-use-this-vs-alternatives routing, and the prescription to 'perform a generic subject enrichment check' within this tool blurs the boundary with the sibling enrich_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?

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?

The description surpasses the annotations by explaining the relational consequences: improves broad search but never determines storage IDs, and is editable rather than a fixed naming decision. It also addresses an important behavioral nuance about preserving disagreement instead of treating alternate labels as proof of a different meaning. No contradiction with the 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?

Each sentence adds meaningful information: the primary action, prerequisite condition, relational side effects, semantic nature, and a subtle edge-case caveat. It is somewhat dense rather than redundant, and the most important contextual 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?

Considering the description, annotations, and sibling tool list, the tool is sufficiently complete for safe and intended use: the agent knows the action, the allowed/disallowed types, the prerequisite tool, and the impact on search/storage. The only minor gap is the absence of any return-value/receipt information, but this is not crucial for an imperatival mutation-like tool.

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

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

The schema has zero property descriptions, so the description must compensate. The phrase 'such as ferry belongs_to transportation' gives a clear example of how source_type, target_type, and relationship map to arguments. However, it does not enumerate possible relationship values or fully explain source/target directionality beyond the example, leaving some free-form semantics to the agent.

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 specifies the action ('Add editable classification metadata') and the object ('between existing subject types'), backed by a concrete example. This also differentiates it from sibling operations like retire_type_relationship or resolve_subject_hierarchy, making the tool's purpose unambiguous.

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

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

The description gives explicit when/when-not guidance: it must only be used with existing types, and unknown types must first be resolved with resolve_subject_hierarchy. It explicitly says this is a semantic assertion, not a naming choice, guiding the agent away from using it as an alias/naming tool. This clearly separates it from sibling tools.

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

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

Annotations already declare non-readonly, idempotent, non-destructive intent. The description expands usefully with impactful specifics: contributions are immutable, votes require evidence with vote= and a non-empty reason, votes are advisory, and the server independently checks acceptance criteria and review IDs. These add real behavioral context beyond the annotation flags. No contradiction with annotations is present. It could have noted response behavior, but that is not essential to authorization.

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 uses four sentences, is front-loaded with the core action, and every sentence provides relevant detail: the resource type, vote evidence constraints, position on advisory votes, and server-side checks. There is no filler or redundancy with the annotations.

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

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

With 9 parameters, no output schema, and no per-parameter schema descriptions, the tool description leaves major gaps: it doesn't explain what content should contain, which parameters are required or optional, how unresolved_points and responds_to_contribution_ids relate to each other, or what kind of response or error to expect. The description gives good behavioral context but is not complete enough to confidently invoke the tool in many cases.

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 of explaining the remaining semantics. It does cover contribution_type semantically (listing the five types) and explains that evidence must include vote=approve|reject|abstain plus a reason for votes. However, it leaves seven other parameters (e.g., content, deliberation_id, idempotency_key, source_model, confidence, unresolved_points) unexplained, so the agent gets only partial support for correct parameter construction.

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

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

The description opens with a specific verb and resource: "Add an immutable proposal, critique, counterproposal, reconciliation or vote." It clearly identifies what the tool does and enumerates the contribution types. It doesn't explicitly contrast itself with sibling tools like create_deliberation or record_resolution, but the object and types are specific enough that an agent can tell the resource apart.

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 implied usage context: you use this tool to add contributions rather than to create a deliberation or resolve one. It states that "Votes are advisory and never resolve a deliberation or activate guidance," which implies rule conflicts with record_resolution, but no explicit alternatives or when/when-not conditions are given. An agent must infer when to prefer this over sibling tools.

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

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

The description goes beyond the readOnly/idempotent/non-destructive annotations by explaining how alias resolution works, using equivalent labels, and separating soft naming disagreement from semantic disagreement. This substantially helps an agent avoid misuse without contradicting any 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 first sentence is excellent and front-loaded, and the policy guidance is substantive. However, later sentences repeat the naming-flexibility idea and include the unclear statement about 'DNS storage paths' and 'review leaf concepts', which adds confusion without clearly earning its place.

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

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

For a zero-parameter read-only inspection tool, the description covers what is listed, when to call it, and how to interpret naming flexibility in practice. Minor details such as return structure or pagination are absent, but the output schema is also absent, and the main usage context is well addressed.

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 no parameters and the empty schema already communicates that fully, so the description has no parameter burden. Since 0-parameter tools get a baseline of 4 and the schema coverage is 100%, the description adds the appropriate surrounding context rather than needing parameter-specific detail.

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

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

The description opens with a specific verb and resource: 'List canonical subject types, aliases, flexible relationships and reusable fields.' This clearly separates it from mutation or resolution siblings and makes the tool's read-only inspection scope 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 explicitly says 'Inspect this before classifying any unknown subject type', giving a concrete invocation context. It also provides boundary guidance on naming vs. semantic disagreement, though it does not explicitly name which sibling tools to use instead.

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