Entity Enricher

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

Even though destructiveHint=true already flags danger, the description adds genuinely important behavioral context: acknowledgement can permanently purge deltas and entity state, it releases a lease, and it returns acknowledged/purged counts. It also states 'No LLM call', which helps an agent decide how to invoke it.

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

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

Four short sentences, each earning its place: core action, side effects, return summary, and workflow reference. The most decision-relevant warning is front-loaded early.

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 100% schema coverage, existing output schema, and destructive annotation, the description covers everything needed for correct invocation: lease semantics, purge risk, success criteria, return counts, and a docs pointer. No critical gap remains.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces that up_to_id bounds the acknowledgement range and mentions returned counts, but it does not add much parameter-level meaning beyond the schema.

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

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

The description uses a specific verb (acknowledge), a precise resource (database deltas up to up_to_id), and states the postcondition (releasing its lease). This clearly differentiates it from sibling tools like fetch_database_deltas and sync_records_to_database.

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

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

It explicitly states when to use the tool—after successful application of deltas—and gives a strong when-not: never acknowledge unapplied or failed work. It points to the apply/ack workflow docs, though it does not name sibling alternatives directly.

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 the annotations by disclosing that omitted nullable means required at enrichment, that adding inside $defs affects every usage site, and that the tool follows the same validation and working-copy/publication rules as update_schema_property. These are meaningful behavioral side effects an agent needs to know.

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 information-dense but every sentence earns its place: primary operation, accepted values, prerequisites, side effects, and reference to documentation. It is front-loaded with the most important scoping information and contains 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 mutation tool with an output schema and rich annotations, the description covers prerequisites, permissions, side effects, and cross-tool references. It even points to the property format documentation. Nothing essential for invoking the tool correctly 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 already covers 100% of parameters, so the baseline is 3. The description adds extra semantics beyond the schema by explaining accepted definition forms (scalar, nested object, reference to $defs or $enums) and the nullable default behavior, which helps the agent construct valid input.

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 ('Add a property') and immediately scopes where it applies: root, object path, or '$defs.X'. It also distinguishes the operation from siblings like update_schema_property and move_schema_property by focusing on the act of adding, not modifying or moving.

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: requires editor, no LLM call, read the container with get_schema_part first, and the same validation/publication rules as update_schema_property apply. It does not explicitly state exclusions or name alternatives for when to use update instead of add, but the purpose is clear enough for an agent to select it correctly.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavioral detail beyond that: editor permission is required, embedding/judge costs may be incurred, resolution refusal behavior, and the fact that embedding_model only affects new concept types. This gives the agent important execution-time expectations.

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 earns its place: core purpose, prerequisites/costs, best-practice probing, refusal behavior, parameter scoping, return-value pointer, and pointer to documentation. It is front-loaded with the main purpose and remains compact despite covering multiple operational considerations.

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, an output schema exists, and annotations cover mutability and destructiveness, the description is complete. It addresses prerequisites, costs, edge cases, alternatives, and even points to further documentation. Nothing critical for correct invocation is missing.

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

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

The input schema already covers all parameters at 100%, so the baseline is 3. The description adds value by explaining alias_of semantics, the refusal behavior for conflicting aliases, and the special scoping of embedding_model to new types only. Most parameters remain schema-described, but the added context justifies a score above baseline.

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: 'Add an identity concept at zero usage, or add text as an alias using alias_of.' It clearly distinguishes the two modes of this tool and implicitly separates it from sibling tools like delete_semantic_concepts and update_concept_alias.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Probe first; if the text already resolves to an incumbent, offer that concept instead of blindly retrying,' and 'Aliases resolving to another concept are refused.' It also names the alternative for managing existing aliases: update_concept_alias.

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 set readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable detail: it persists a record (so not read-only in the strict sense) but does not modify the sample, and it is billed. This clarifies the exact side effects beyond the annotations. There is no contradiction; the description enriches the behavioral context.

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

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

The description is informative but a bit dense with several clauses and a doc link. It front-loads the purpose and then covers side effects, usage, and output. While not minimal, every sentence contributes value—no wasted words. It earns a 4 for being structured and efficient without being overly terse.

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 (3 parameters, nested objects, output schema exists), the description covers prerequisites, side effects, usage context, and output semantics. It even points to a documentation resource for interpretation. The output schema is present, so return values are structured. Nothing critical is missing for an agent to correctly invoke and understand the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add per-parameter detail beyond what the schema provides. It mentions 'protected_fields' indirectly via 'Leaf names you own,' but that is also in the schema. It does not explain the 'model' parameter or the exact structure of 'sample_json' beyond the schema. Thus it meets the baseline but adds no extra semantic value.

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-resource pair: 'Analyze sample property ambiguity and relationship identity scoping before schema generation.' This clearly distinguishes it from siblings like analyze_schema and generate_sample. It also states what it produces (findings with competing interpretations and suggested_names) and the scoping output, making the tool's purpose unmistakable.

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

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

It explicitly states when to use the tool: 'before schema generation' and 'Apply only approved corrections before create_schema_from_sample.' It also notes a prerequisite ('Requires editor') and a side effect ('billed analysis persists a record but does not modify the sample'). It references an alternative: 'Optional: generate_sample already checks its initial sample,' which helps the agent decide whether this tool is needed. This is thorough 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 declare readOnlyHint=false but leave the mutation unspecified; the description fills that in by naming the writes (annotations to the schema), the billing implication, the incremental-vs-full execution model, and the error condition. It also explicitly bounds scope — suggested structural changes are not applied, they come back as pending proposals — which prevents an agent from assuming edits landed.

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

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

Front-loaded with purpose and side effect, then progressively narrower operational facts; every sentence carries distinct information. It is dense telegraphic prose ('Requires editor; billed.') that is efficient but verges on terse jargon with terms like 'identity scoping' and 'unification proposals' left unexplained.

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?

An output schema exists, yet the description still sketches the return payload (findings, suggested descriptions, identity-scoping annotations, pending proposals), which is the piece an agent most needs to chain this into review/approval steps. Combined with role requirements, billing, error mode and the docs URI, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics for force ('rechecks all sites' vs incremental default) that the schema only phrases as 're-analyze every property'. The model parameter is left entirely to its schema description.

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

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

States a specific verb and resource plus the exact scope: property ambiguity and relationship identity scoping on a saved schema, with the side effect of writing annotations. That distinguishes it from get_schema (read-only retrieval), update_schema_property (per-property edits), and publish_schema.

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

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

Gives concrete operating guidance: requires editor role, is billed, incremental by default, force=true to recheck everything, and fails with ambiguity_check_disabled when the feature is off. It also routes to update_schema_property for approved descriptions or renames. What's missing is the triggering condition in the workflow — nothing says when in the schema lifecycle to call this rather than after save_schema or before publish_schema.

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

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

The description goes well beyond the annotations by disclosing that resuming 'may continue billed model work', that omitted answers use defaults, and that consequential unanswered choices should be relayed unless already authorized. It also explains the return behavior and polling fallback, which the annotations do not cover.

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

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

The description is compact and front-loaded with the core action. Each sentence adds necessary information: answers structure, default behavior, cost implication, return behavior, polling alternative, and compatibility. There is no filler or redundant restatement of schema fields.

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 description covers the input contract, default behavior, cost implications, return semantics, and follow-up polling. It also references enricher://docs/documents for further detail. Nothing critical appears missing for an agent to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds meaningful semantics: it defines the answers map structure as '{option_ids: [...], text: ...}', explains that omitted questions use defaults, and clarifies wait_seconds behavior by describing what is returned after the wait. This enriches the schema significantly.

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: 'Resume a paused job with answers to the questions returned under pause.' This clearly differentiates the tool from siblings like cancel_job and get_job_status, and the title 'Answer job question' is expanded into a concrete action.

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 when to use the tool: when a job is paused and questions were returned. It also provides routing guidance by saying to 'poll get_job_status if still running' and mentions compatibility with generate_sample clarification. It lacks an explicit when-not-to-use statement, but the context is clear enough.

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 say this mutates state, is open-world, and is non-destructive, but the description adds critical behavior beyond them: the platform validates the answer like a provider, rejected answers return as new requests with tool_result errors, and the tool may return pending requests, a terminal result, or running status depending on wait_seconds.

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

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

Although dense, the paragraph is front-loaded with the core task and then layers in response shape, validation behavior, return semantics, and exclusions. Every sentence carries operational information needed to invoke the tool correctly, with no filler.

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

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

The tool has a complex nested response object and an output schema, but the description still explains return values and validation loops. Combined with full schema coverage and annotations, it gives an agent everything needed to call and recover from errors 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 coverage is already 100%, and the description still adds substantial meaning: it specifies the exact response shape, explains that toolChoice.mode 'required' means one matching tool_use block, and clarifies that wait_seconds controls waiting for the next pending request, pause, or completion.

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: answer one delegated LLM request by running it on the caller's own model and passing back an MCP CreateMessageResult-shaped response. It explicitly distinguishes this from question pauses via answer_job_question, so the agent can differentiate it from nearby siblings without inspecting 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?

It gives explicit context: use this for every start tool's default unless use_platform_models=true or an explicit platform model is configured. It also names the exclusion ('Not for question pauses') and points to answer_job_question, making the when-to-use boundary 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing blocking latency (~2 minutes), quota consumption with the concrete questions_remaining field and support_question_limit_reached failure, auth requirements with the support_requires_user error, and the asynchronous new_admin_messages follow-up protocol. This is unusually rich operational context for a tool whose annotations say little.

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

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

Front-loaded with purpose, then prerequisites, then quota and follow-up mechanics — the ordering matches how an agent needs it. It is a single dense paragraph of roughly 180 words, and the attachment sizes/limits partly restate the schema, so it is close to the upper bound of acceptable length rather than wasteful.

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?

An output schema exists, yet the description still flags the two return fields an agent must act on (questions_remaining, new_admin_messages/threads_with_unread_admin_reply). Combined with auth, quota, latency and attachment constraints, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the baseline would be 3. The description still adds workflow semantics the schema does not: which context to pack into message (tool called, error_code, schema/job ids, never secrets) and the continue-vs-new-topic rule for conversation_id.

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?

Names a specific agent and resource: 'Ask Rupert, Entity Enricher's product-support assistant, a question about the application itself', then enumerates the question classes (feature behavior, error_code meaning, plan requirements). This is clearly separable from siblings like get_support_conversation, list_support_conversations and answer_job_question.

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

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

Explicit trigger and fallback chain: use it when enricher://docs does not answer, 'before guessing or telling the user something is impossible'. It also routes the continuation case to conversation_id and the reading case to get_support_conversation, so alternatives are named with their selecting conditions.

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

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

Annotations only declare safety flags, so the description carries the burden of behavior. It discloses that assignment may create the physical database and start synchronization automatically, revokes the old host's minted credential on host move, and does not evict existing manual pairings. This is rich, non-obvious context beyond 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 front-loaded with the core operation and each subsequent sentence adds meaningful behavioral or prerequisite detail. It is dense but not bloated, and the doc link provides optional depth without cluttering the main guidance.

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

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

For a mutating tool with an output schema, the description covers prerequisites, side effects, parameter sourcing, and gotchas like credential revocation and manual pairing preservation. Nothing critical is missing for an agent to invoke this tool correctly.

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

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

Input schema coverage is 100%, so the schema already documents both parameters. The description adds some nuance by explaining null means unassign and naming candidate sources, but most parameter meaning is already present in the schema.

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

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

The description uses a specific verb pair, 'Assign or clear,' and names the exact resource, 'the host provisioning a database sync.' It clearly distinguishes this from related tools like create_database_sync and list_database_syncs by specifying that candidates come from those 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 explicit prerequisites (owner, sync-enabled plan), parameter semantics (null to unassign), and candidate sourcing from create_database_sync or list_database_syncs. It does not fully enumerate when to avoid this tool versus sibling assignment alternatives, but the guidance is otherwise 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?

Adds important behavioral details beyond annotations: in-flight model calls may finish and persist records, remaining work is skipped, cancellation does not roll back writes, and no new LLM call is started. These consequences are material and not derivable from the annotation hints 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?

Three dense, purposeful sentences: action and state scope first, then behavioral consequences, then follow-up guidance. There is no filler, repetition of schema fields, or unnecessary background.

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 well-documented parameter and an output schema, the description covers action, effects, persistence semantics, side effects, and recommended follow-through. Nothing needed for correct invocation or interpretation 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 only parameter, job_id, is already fully described in the schema as 'Job ID to cancel' with 100% coverage. The description references job_id in the follow-up example but adds no new semantic detail 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?

States a specific verb and resource: 'Request cancellation of a pending, running or paused LLM job.' It also distinguishes itself from read/delete-like operations by explicitly noting cancellation is not a rollback. This leaves no ambiguity about what the tool does.

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

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

Provides clear post-conditions and next steps: inspect outcome via get_job_status and list_records(job_id=...). It implies when to use the tool, though it does not explicitly enumerate alternatives or cases where cancellation is inappropriate. The context is strong enough for an agent to select it 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?

Goes well beyond the annotations by disclosing cost ('billed analysis'), the required role, incremental-vs-full analysis semantics, and the polling/output contract. The one flaw is the unconditional 'billed' framing, which sits awkwardly against the schema's statement that the default use_platform_models=false consumes no credits and parks calls as pending requests — an agent could wrongly assume default invocation is paid.

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

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

Front-loads the core action and cost, then prerequisites, then the call→poll→correct→publish workflow, with a docs pointer at the end. Dense but nearly every clause carries operational information; the mid-sentence pivot into 'incremental scope' wording is the only slightly tangled part.

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 though an output schema exists, the description still tells the agent what comes back (job_id) and how to consume it asynchronously, plus role requirements, cost model, and the full downstream workflow. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so model, schema_id and use_platform_models are already fully documented — baseline 3 applies. The description adds model-agnostic framing but does not clarify parameters further, and it references an 'incremental scope' that has no corresponding parameter in the schema, which could send an agent looking for a control that does not exist.

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 ('start a billed analysis proposing database keys, SQL types, indexes and relationship ownership on a linked schema'), which is far more precise than the sibling analyze_schema or publish_schema. It also delineates it from registration ('Registration already starts the initial pass'), so an agent knows exactly which stage this tool occupies.

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

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

Explicit triggering condition ('use this after relevant edits'), explicit exclusion ('an empty scope does not rerun unchanged fields' — do not call when nothing changed), prerequisite ('Requires editor'), and a complete follow-up path: poll get_job_status, inspect get_schema's working copy, correct via property tools, then publish_schema.

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

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

Beyond the readOnlyHint=false annotation, the description discloses that the tool only creates and does not run models, requires an owner and plan, returns the scenario and link, and refuses entity_data that carries no value. It also surfaces the preconditions for later execution, giving a clear behavioral contract.

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

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

The description is dense but every clause carries routing or behavioral information; the mandatory judge and scenario-type dispatch are front-loaded, and no sentence is 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 17-parameter tool with three scenario modes, the description provides type-specific requirements, reference preconditions, owner/plan prerequisites, a link to docs, and a follow-up call, while the output schema covers return values. Nothing essential for correct invocation is missing.

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

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

Schema coverage is already high (94%), but the description adds cross-tool semantics: entity_data is 'the same JSON enrich_entity takes', sample_request follows 'same contract as generate_sample's request', entity_samples are '1..20 samples of one entity type', and the entity must 'never' go in description. This materially improves parameter understanding.

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

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

The description opens with a precise verb-resource pair: 'Create a reusable benchmark with a mandatory scoring judge.' It then enumerates the three scenario_type branches and references related tools, making it clearly distinct from execution tools like run_benchmark and update/delete siblings.

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

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

It gives direct when-to-use rules per scenario_type ('needs schema_id and entity_data', 'needs sample_request', 'needs entity_samples'), states the gold-reference prerequisite via set_benchmark_reference, and names the next action (run_benchmark) once reference requirements are met. This is explicit routing with alternatives.

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

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

Beyond annotations, the description discloses important behavior: billing implications of classification, return fields, webhook secret exclusion, initial unpublished state, pk_strategy locking, replacement semantics for owned child arrays, purge custody transfer, and the custody_warning relay requirement. These are material behavioral traits an agent needs before invoking a creation tool with side effects.

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

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

The description is front-loaded with the core purpose and packs necessary workflow, side effects, and alternatives into a dense paragraph. It is appropriate for a 16-parameter creation tool, though the density is high and some clauses could be easier to scan with stronger 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 complexity, rich input schema, annotations, and output schema, the description covers the key missing context: prerequisites, return fields, publication workflow, host provisioning paths, locking behavior, purge warnings, and documentation links. An agent has enough information to call the tool correctly and know 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?

Schema description coverage is 100%, so the schema already carries the parameter documentation burden. The description mentions some parameter consequences (pk_strategy locking, purge_entity_state custody transfer, target_host provisioning), but these largely restate the schema rather than adding substantial new semantic 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 states a specific verb and resource: registering a saved schema for relational synchronization to PostgreSQL, MySQL, or SQLite. It clearly distinguishes creation from sibling operations like list_database_syncs, delete_database_sync, sync_records_to_database, and publish_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 explains prerequisites (owner and sync-enabled plan), the post-creation workflow (wait for classification, review keys/options/notices, then publish_schema before sync), and alternatives for host provisioning (assign_sync_host or get_database_setup_instructions). This gives an agent explicit routing guidance rather than leaving usage 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?

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=true): discloses that it auto-saves, requires editor role, is synchronous and billed, will not redesign an approved structure, and that semantic IDs need an organization embedding model and add cost. That is exactly the behavioral context an agent needs before committing to a paid synchronous mutation.

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

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

Dense and front-loaded — the core action and its returned identifiers come first, followed by input rules, then pre/post-call obligations and doc links. It is long for a single paragraph with heavy semicolon chaining, but nearly every clause carries an instruction the agent would otherwise miss.

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?

Complete for a 10-parameter, high-complexity generation tool: an output schema exists and the description still names what comes back, permission and billing models are stated, the semantic-ID decision is flagged as needing user agreement, and two enricher:// doc links cover sample review and schema format.

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 baseline is 3. The description explains the entity_samples/samples_csv exclusivity and the sample_record_id fallback ('its stored samples are used when entity_samples is omitted'), but the override-precedence and semantic-ID cost statements largely restate what the per-parameter descriptions already say, so it adds some, not much, net 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?

States a specific verb and resource ('Generate and auto-save a schema from reviewed samples') plus the return payload (schema_id, schema content, record links), which lets an agent separate it from update_schema/save_schema/publish_schema siblings without opening a schema.

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

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

Explicit about acceptable input combinations ('entity_samples (or samples_csv), sample_record_id, or both'), override precedence, and when to settle modeling decisions before calling. It also routes the agent onward ('review returned suggestions before applying edits with property tools') but never names a sibling it should be used instead of, so the exclusions are implied rather than stated.

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

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

The description discloses that deletion is permanent and includes the stored file, that existing records remain, and that the deleted source cannot be reused. This adds significant behavioral context beyond the destructiveHint annotation, which only indicates destructiveness. It also notes 'No LLM call', a useful operational detail.

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 (three sentences) and front-loads the core action, then adds essential caveats about permanence and when not to use. Every sentence adds value without redundancy.

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

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

The tool is simple (one parameter) and has an output schema, so return values need no explanation. The description covers purpose, scope, conditions, and consequences thoroughly, making it complete for an agent to decide and invoke correctly.

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

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

The schema already fully documents the single parameter attachment_id with type and description (coverage 100%). The tool description adds no additional meaning or context about the parameter itself, so the baseline 3 applies.

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

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

The description clearly states the verb 'delete', the resource 'attachment', and the scope 'in your organization, including its stored file'. It distinguishes itself from sibling delete tools (delete_schema, delete_benchmark_scenario) by specifying the attachment domain, and it clarifies it is not a required post-enrichment step, making its 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 provides explicit usage guidance: 'Delete only when that source is no longer needed' and explicitly states 'this is not a required post-enrichment step', preventing misuse. It also notes that future calls or schema regeneration cannot reuse the deleted source, which helps the agent decide when deletion 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 meaningful behavioral context beyond the annotations. It confirms that the tool deletes both the scenario and its stored results (specifying the destructive scope), notes that it requires ownership and a plan with benchmarks, clarifies that no LLM call is involved, and advises inspecting the scenario before deletion. These details enrich the understanding of side effects and prerequisites, and they do not contradict the annotations (readOnlyHint false, destructiveHint true, 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 is three sentences, front-loaded with the core purpose ('Delete a benchmark scenario and its stored results') followed by essential usage and safety notes. Every sentence earns its place with no redundancy or 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 the simplicity of the tool (one parameter, output schema present, annotations covering destructive and idempotent nature), the description covers all critical aspects: what is deleted, required ownership/plan, absence of LLM call, and a safety caution. Nothing essential is missing for an agent to use it correctly.

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

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

The schema has 100% description coverage for the single parameter scenario_id, already documenting it as the UUID of the scenario to delete. The description does not add parameter-specific information beyond that, so it meets the baseline but provides no extra semantic value.

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

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

The description clearly states the verb 'Delete' and the resource 'benchmark scenario and its stored results', which is specific and distinguishes it from sibling tools like get_benchmark_scenario or update_benchmark_scenario. The phrase 'and its stored results' adds clarity about the full scope of the operation.

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

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

The description provides practical usage context by specifying prerequisites ('Requires owner and a plan with benchmarks') and a caution ('inspect the scenario before deleting it'). While it doesn't explicitly name alternatives or state when not to use it, the purpose is self-evident for a delete operation, and the guidance is sufficient for an agent to decide when to invoke 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?

Goes beyond the destructiveHint annotation by detailing exactly what is deleted (registration, queued deltas, feed) and what is preserved (external replicas, entity state, schema flags by default). It explains the side effects of the optional flags and their irreversibility, and even warns to obtain 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?

The description is moderately long but each sentence contributes unique information: action, requirements, side effects, options, and a doc link. It is front-loaded with the core purpose and logically organized, though slightly dense.

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 operation with three parameters, the description covers prerequisites, exact side effects, default behavior, and irreversible options. It also references documentation for deeper details. Combined with the output schema (not shown but present), the agent has enough to call it correctly.

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

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

Although schema coverage is 100%, the description adds critical nuance: it explains that clear_database_model implies delete_entity_state, and clarifies the meaning of 'schemas left with no registration'. This is not present in the schema and is essential for correct parameter usage.

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 ('Delete a database registration and its queued deltas') with clear scope, distinguishing it from sibling tools like delete_schema or delete_attachment. It also names prerequisites (owner, sync-enabled plan) which further clarifies 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?

Provides clear prerequisites (owner, sync-enabled plan, no LLM call) and what remains untouched (external replica tables). It doesn't explicitly name alternatives, but the purpose is distinct enough that an agent can infer when to use it. The note about obtaining approval for irreversible teardown options is useful 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 mark the tool as destructive and idempotent, but the description adds substantial behavioral context beyond that: the operation is a soft delete, editor permission is required, no LLM call is made, and the tool cannot restore or permanently delete. This gives an agent an accurate model of side effects even though destructiveHint is present.

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

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

Three short sentences, each earning its place: the operation and target, the requirements and constraints, and the return behavior. The most decision-relevant information is front-loaded, 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 single-parameter tool with an output schema, the description is fully sufficient. It covers what the tool does, under what permissions, what side effects it has, and what it will not do. No important operational detail an agent needs before calling it is missing.

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

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

Schema description coverage is 100% since schema_id is documented as 'UUID of the schema to delete.' The tool description repeats that the operation targets a saved schema by UUID but adds no new parameter-level meaning. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 plus resource: 'Soft-delete a saved schema by UUID.' It adds the soft-delete nuance, which distinguishes it from permanent deletion and from sibling tools that delete other resource types. The phrase 'Returns the deletion outcome' completes the picture 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 conditions of use: it requires editor permissions, it is not an LLM call, and it only supports soft deletion. It explicitly states that restoration and permanent deletion are not available through this tool and belong to the web app, which is a useful when-not. It does not name a specific sibling tool as an alternative, but for a schema delete operation that is not necessary.

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

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

Annotations already mark the tool as destructive and not read-only, but the description adds substantial behavioral context: impact-only review, role-based permission requirements, convergence-breaking consequences, future ID minting, unused-only still removing vocabulary, and absence of LLM calls. This far exceeds 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 dense but every sentence carries essential information: selection method, safety default, permissions, long-term side effects, execution behavior, return value, and reference docs. It is front-loaded with the core action and immediately provides decision-relevant constraints.

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 four parameters, annotations, and an output schema, the description covers all necessary decision points: what is deleted, how to limit impact, who may execute, what side effects occur, what is returned, and where to find further documentation. No critical operational context is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful relational semantics beyond the schema, such as how ids, concept_types, and unused_only interact, the owner-role requirement for clearing whole types, and the impact_only default. This lifts it above the baseline.

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: 'Delete concepts selected by ids, concept_types or unused_only.' It clearly identifies the object being deleted and the selection criteria, distinguishing it from sibling tools that delete schemas, attachments, or syncs.

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 operational context: impact_only defaults to true, approval is needed, editor vs owner role requirements are stated, and a docs link is provided. It does not explicitly name sibling alternatives or state when not to use this tool, but the selection criteria and role conditions make the intended usage clear.

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

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

Annotations only say readOnly=false, destructive=false, openWorld=true; the description adds the critical behavioral layers – generation is billed, fusion requires all legs to succeed, database admission is not replica delivery, partial writes/overwrites can occur, and the default YOUR-model path parks calls as pending requests. It also discloses the classification-warning pause semantics that differ between the local and platform execution modes.

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

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

Purpose is front-loaded, but the body is a dense run-on paragraph that mixes billing, fusion failure, classification, database sync, delegation mode, and recovery into one block. Each clause carries information, yet the lack of structure (no separation of the YOUR-model vs platform-model paths) makes it harder to parse than its length warrants.

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 15-parameter tool with an output schema, the description covers execution modes (local vs platform billing), timeout/recovery, fusion failure detection, database-sync warnings, and points to enricher://docs/enrichment-and-fusion for the recovery ladder. Since an output schema exists, it correctly avoids re-explaining raw return values while still flagging the salient outcome fields.

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 all 15 parameters are already documented in the schema. The description reinforces a few (auto model omission, database_sync recovery case, force_after_classification_warning), but adds little beyond what the schema text already states, including the mutual exclusion and web-search behavior. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a specific verb and resource (enrich one entity), names the exact mutually-exclusive input (schema_id vs target_schema), and lists what comes back (structured output, record_id, costs, database outcome). An agent can immediately distinguish this single-entity tool from start_batch_enrichment and merge_records mentioned later.

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

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

Explicitly routes the agent: read get_schema.input_contract first, never invent preserve values, omit models for auto, use start_batch_enrichment for long fusion/reasoning runs, set database_sync=false only for the recovery leg of a failed fusion, and bypass classification_warning only after user confirmation. It names the alternatives (retry_expertises, merge_records, answer_job_question, answer_llm_request) and the conditions that select them.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the disclosure burden. It goes beyond them by detailing lease duration, replayability, transactional application, page_limit bounding, snapshot pause behavior, and the fact that no LLM call is made. This is strong behavioral transparency.

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

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

The description is dense but every sentence carries distinct information: scope, replay/lease semantics, transactional ordering, limit constraint, snapshot gating, and a pointer to detailed docs. It is front-loaded with the core read action and wastes no words.

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 sync-consumption tool with an output schema, the description covers the operational essentials: lease behavior, acknowledgment dependency, ordering, limit interaction, and snapshot handling. It also links to documentation for leasing, cursors, quarantine, and snapshot handling, so an agent has enough context to invoke it correctly.

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

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

With 75% schema coverage, the schema already explains database_id, claim, and since. The description adds meaning by explaining that claim=false is replayable while claim=true leases the window, and that limit is also bounded by the registration's page_limit. This usefully supplements the schema rather than repeating it.

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

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

States a specific action and resource: 'Read the next ordered window of SQL deltas and canonical payloads for a database sync.' This clearly distinguishes it from acknowledge-only or sync-management siblings such as ack_database_deltas and create_database_sync. The scope of the operation is unambiguous.

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

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

Provides actionable guidance on claim=false vs claim=true, the 120-second lease, and the requirement to apply a claimed window before calling ack_database_deltas. It does not explicitly enumerate when-not-to-use alternatives, but the coordination with ack_database_deltas and replayability semantics give clear context.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description goes far beyond by disclosing the editor requirement, that generation is billed, that it runs as a job which may return already paused or complete, that no credits are consumed when running on YOUR model, and that samples must not have facts silently changed.

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

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

Front-loaded with the core purpose and mode split before the job-flow instructions, and nearly every sentence carries operational weight. It is dense and long, but density is justified by the 13-parameter, two-mode surface; a couple of clauses (e.g. the repeated source-only reminder) could be trimmed.

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

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

For a complex, dual-mode job tool with 13 parameters and an output schema, the description covers what the output schema cannot: async job lifecycle, pause handling, billing implications, and the hand-off to create_schema_from_sample. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns extra credit by adding cross-parameter rules the schema does not state — instance count belongs in sample_count not request, each sample is one instance in one language, and any attachment forces one sample. Remaining params (model, auto_answer, wait_seconds) are explained only in 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?

Opens with a specific verb+resource+output ('Generate editable sample JSON ... for schema authoring') and immediately frames the two operating modes (knowledge vs. attachment/source). An agent can tell it apart from sibling create_schema_from_sample (consumes samples) and analyze_sample (inspects them) without opening any schema.

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

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

Explicit routing: use answer_job_question for pause questions, otherwise poll get_job_status; review samples and warnings before calling create_schema_from_sample; read enricher://docs/schema-from-sample for relationship modeling or multi-document work. It also states the when-not condition (attachments force one sample, search does not relax source-only extraction).

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=falsehistorically. The description adds meaningful behavioral context beyond this: 'No LLM call' clarifies cost/latency characteristics, while 'Config changes can make existing results stale' warns about data freshness. It also explains the side effects of include_reference=true, which is a behavioral trait not evident from 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 four short sentences, each contributing essential information: what the tool returns, the parameter effect, a staleness warning, and a routing hint. It is front-loaded with the core purpose and has zero 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 is a simple read with an output schema present, so return values need no elaboration. The description covers the main use case (after run_benchmark), the caveat (config changes), the parameter semantics, and the alternative tool. Nothing an agent needs to safely and effectively invoke it is missing.

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

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

Schema description coverage is 100%, so a baseline of 3 is expected. However, the description adds value by explaining that include_reference=true adds not only reference_output and entity_data (already in the schema) but also 'the schema-generation entity_samples', which is not mentioned in the schema. This clarifies the parameter's full impact beyond the structured definition.

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

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

The description states a specific verb ('Read one benchmark scenario') and the resource with its content ('per-model quality, cost and speed results'). It also explicitly distinguishes from the sibling get_benchmark_scenario_results by noting that the sibling returns a 'ranked subset', which is a clear differentiation.

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

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

Provides explicit usage guidance: 'Read after run_benchmark completes' and 'For a ranked subset use get_benchmark_scenario_results'. It also warns about staleness with 'Config changes can make existing results stale', helping agents decide when to refresh or trust the data.

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 readOnlyHint/destructiveHint annotations, the description discloses key behavioral nuances: 'overall' is a weighted blend that becomes null if any component is missing, status tags are independent (success does not exclude stale/stale_score), and missing sort metrics always sort last. These are critical for correctly interpreting results and are not visible in 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?

Three sentences with no wasted words. The opening verb phrase immediately states the action, followed by essential behavioral caveats and a pointer to docs. Each sentence contributes distinct information, and the most important constraints (status independence, null handling) are 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 presence of an output schema means return values need not be described. The description covers filtering, ranking, limiting, and the tricky semantics of nulls and status tags. It also provides a documentation link for deeper interpretation. Nothing essential for correct invocation is missing.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the meaning of 'overall' (weighted blend) and the independence of status tags, which are not fully captured in the parameter descriptions. This goes beyond the schema's per-parameter docs, though it doesn't exhaustively cover every parameter nuance.

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 (filter, rank, limit), a specific resource (a scenario's per-model benchmark results), and the scope (per-model). It distinguishes itself from siblings by focusing on retrieving and ranking results rather than creating or running benchmarks. The 'No LLM call' clarification reinforces its read-only 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?

The description clearly implies this is the tool for retrieving and ranking existing benchmark results, with explicit filtering and sorting semantics. It does not explicitly name alternatives or when-not-to-use conditions, but the context (read-only, results-focused) makes the use case unambiguous. A brief reference to the docs for interpretation adds some 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 readOnly and non-destructive annotations, the description discloses meaningful behavior: no LLM call, no credential issued or exposed to the MCP client, the DSN stays on the host, and the pairing flow is browser-confirmed. This gives an agent an accurate mental model of side effects and security boundaries.

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

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

The description is dense but efficient: purpose is front-loaded, followed by prerequisites, security-relevant behavior, the pairing flow, and a clear when-to-use caveat. Every sentence adds information an agent needs for correct invocation.

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

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

Given the tool has a single documented parameter, an output schema, and read-only annotations, the description covers the remaining operational context: required permissions, setup steps, credential handling, and the manual-pairing condition. Nothing essential is missing.

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

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

Schema description coverage is 100%, and the single parameter 'database_id' is documented with its source ('from list_database_syncs'). The tool description does not add parameter-specific detail, but the schema already carries the necessary meaning, so the baseline of 3 applies.

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: 'Return non-secret install, browser-confirmed pairing and run instructions for an ee-database sync client.' This goes well beyond the title and makes the tool's function unambiguous relative to related database-sync siblings.

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

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

It states preconditions ('Requires owner and a sync-enabled plan') and gives an explicit routing rule: 'Use manual pairing only when managed host provisioning is not already handling the registration.' It does not name sibling tools as alternatives, but the context is clear enough for an agent to decide 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a read that does not edit the enum, it makes no LLM call, and it reports counts from recent enrichment records. This goes beyond the annotations by explaining the operation's non-mutating nature and data source.

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

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

The description is compact and front-loaded: the core action and scope appear in the first sentence, followed by usage guidance and exclusions. Every sentence adds value, and the reference to enricher://docs/schema-reference is a useful pointer without bloating the text.

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 tool with a full output schema and annotations covering safety, the description is complete. It explains the purpose, the open/closed enum distinction, when to use it, and what it does not do. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter (schema_id as UUID of the saved schema). The description does not add parameter-specific details beyond what the schema provides, but with full coverage the baseline of 3 is appropriate.

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 ('List') and resource ('observed values outside each open enum's current vocabulary'), and distinguishes it from related tools by noting it is a read that does not edit the enum. It also clarifies the distinction between open and closed enums, which helps an agent understand the tool's exact 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 explicitly says when to use this tool: to propose admitted members or rejected_values, or to close a vocabulary only when exhaustive. It also names alternatives (get_schema_part for reading named enums, update_schema for changing them) and states that this tool does not edit the enum, providing clear 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?

Goes well beyond the readOnly/destructive annotations: it discloses that a failed job is not usable output, that unknown IDs may be invalid, expired, or lost after restart, that no LLM call is made, and that event logs are capped at 100 per call with events_has_more signaling. These are the failure and recovery traits an agent cannot infer from 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?

Front-loaded with the core purpose and the six status values, then layers routing, failure, and cursor details. It is dense and mostly earns its length, though the long run-on sentences (events_after and llm_request_id clauses) make it read as a wall of text.

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 polling status tool with an output schema already documenting returns, this covers the remaining burden: status vocabulary, failure interpretation, restart-loss recovery path, event-log pagination, and a documentation pointer for deeper polling/recovery guidance. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real semantics on top by framing events_after as the poll equivalent of the SSE stream with the last_seq continuation pattern, and by explaining the relationship between the llm_requests list and llm_request_id. It stops short of full detail on include_result size implications, which the schema already covers.

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 (read) and resource (job status) plus the exact payload shape: status, progress, compact terminal summary with persisted record IDs. It also enumerates the status vocabulary, so an agent knows precisely what this returns and how it differs from sibling tools like cancel_job or list_records.

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

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

Explicitly routes the agent elsewhere for every adjacent case: relay pause questions to answer_job_question, answer delegated llm_requests with answer_llm_request, and use list_records(job_id=...) to recover persisted outputs for unknown IDs. It also distinguishes polling from the SSE stream via the events_after cursor, which is exactly the when-to-use guidance a status tool needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower, but the description still adds substantial behavioral context: 'No LLM call' signals cost/latency profile, 'failed_expertises and partial identify incomplete work even when output exists' reveals that a returned record may still represent failed work, and it explains the semantics of fusion metadata and the conditional database_sync field. No contradiction with annotations — 'Read' and 'No LLM call' align with the read-only hint.

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

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

The description is dense but well-structured: core purpose first, then result-interpretation semantics, sibling routing, metadata meaning, and finally cost/docs pointers. Every sentence carries distinct information with no filler, though it is on the longer side and slightly front-loads detail before the simplest 'no LLM call' takeaway.

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 tool with an output schema and safety annotations, the description covers everything an agent needs: what fields the record contains, how to detect incomplete/failed work, which sibling to route to for recovery, what fusion metadata means, the meaning of the conditional database_sync field, and a docs link for interpretation. Nothing essential is missing.

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

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

Schema coverage is 100%: the single parameter record_id is already documented as 'UUID of the record.' The description reinforces this via 'one persisted record' but adds no parameter-specific format, validation, or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter documentation burden.

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-resource pair ('Read one persisted record's...') and enumerates exactly which fields are returned (structured_output, entity_input_data, validation errors, expertise verdicts, metrics). The singular scope 'one persisted record' cleanly distinguishes it from list_records, and the focus on enrichment/verdict data separates it from get_schema and get_stats.

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 routing guidance: 'use retry_expertises only on a record with failed domains', telling the agent when a sibling is appropriate and what precondition must be checked first. It also clarifies interpretation ('failed_expertises and partial identify incomplete work even when output exists') and points to recovery docs. It does not explicitly contrast with list_records or get_stats, but the read-one-record scope implies the boundary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds value by stating 'No LLM call', explaining the not_found behavior for a missing published contract, and describing response fields (version, publish_state, schema_url). It also discloses the semantics of identifying_keys and preserve values, which goes beyond the annotation baseline.

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 longer than average but every sentence carries substantive content: purpose, version selection, entity-naming guidance, error behavior, and a pointer to documentation. It is front-loaded with the core purpose and ends with a contract reference. Some redundancy with the schema exists, but it is not padded.

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 an output schema present, the return format is already documented. The description covers version selection, error cases (not_found), the distinction from get_schema_part, and the special semantics of identifying_keys and preserve values. No critical information for a correct call is missing; the agent knows exactly when to call it and what to expect.

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 100%, so the baseline is 3. The description enhances parameter understanding by clarifying the version semantics (working vs published and their respective use cases) and notes that schema_id is a UUID. It adds practical guidance on how to choose the version, which the schema only partially covers.

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

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

The description opens with a precise verb-resource pair: 'Read a saved schema' and enumerates exactly what is read (properties, annotations, input_contract). It also implicitly distinguishes itself from get_schema_part by saying 'For a small edit prefer get_schema_part' and from list_schemas by focusing on a single saved schema. This makes 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?

Explicit usage guidance is given: use version='published' before enrichment for database-linked schemas, default 'working' for editing, and prefer get_schema_part for small edits. These conditions directly tell an agent when to choose this tool over alternatives, satisfying the 'when/when-not' requirement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it 'Reads the working copy; no LLM call', which informs cost and latency, and it details what the response identifies (shared definition usage, identity participation, etc.). It also warns that 'Editing a $defs property affects every usage site', a useful consequence for the editing workflow. This goes beyond the annotations and enhances transparency.

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

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

The description is dense but well-structured: it opens with the core purpose, then explains path syntax, response content, an editing caveat, and finally a note on working copy/no LLM. Each sentence adds value; there is minimal redundancy. While it is longer than minimal, it is organized front-loaded and earns its length through necessary usage 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 presence of an output schema (which defines the return format) and annotations covering read-only/destructive safety, the description completes the picture by explaining how to target different schema parts, what the response highlights, and the implication of editing shared definitions. It also clarifies the working copy and no-LLM behavior. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds meaning beyond the schema by detailing path variants ('$defs.X', '$enums.X', object/leaf paths) and giving the array syntax '[]'. It also provides a concrete example (enricher://docs/schema-reference), which helps an agent construct valid paths. This exceeds the baseline for high 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: 'Read only the schema fragment needed for an edit.' This clearly states the tool's function and its scoped purpose, distinguishing it from siblings like get_schema (which likely returns the full schema). The detailed path semantics further clarify exactly what can be fetched, leaving no ambiguity about the tool's 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 provides strong contextual guidance: it's for reading a fragment 'needed for an edit', and it gives explicit path syntax (e.g., '$defs.X', '[]' for arrays). However, it does not explicitly name alternatives or state when NOT to use this tool (e.g., 'for the full schema, use get_schema instead'). The context implies the right usage but lacks an explicit exclusion or comparison.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful behavioral context: 'Record links are capped; records_truncated signals omitted links,' 'neighbors_limit=0 skips neighbors,' and 'No LLM call.' These details go well beyond what annotations alone provide and set accurate expectations about output limits and deterministic behavior.

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

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

The description is dense but every sentence adds value: capabilities, output truncation, parameter edge case, downstream use, determinism, cross-space warning, and a docs pointer. Front-loading the main function makes it immediately scannable for an agent.

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 small parameter count, strong annotations, and presence of an output schema, this description is complete. It covers what is returned, how results are limited, how neighbors can be skipped, how to use the results, and important constraints. An agent can invoke this tool correctly without needing additional clarification.

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 50%, with concept_id documented but neighbors_limit lacking a description. The description compensates by explicitly explaining 'neighbors_limit=0 skips neighbors' and clarifies nearest-neighbor behavior with 'within its own type/model slice.' It does not add much for concept_id, but the schema already covers that parameter adequately.

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: 'Read one concept's aliases, identity source keys, linked records and nearest neighbors.' It also adds scope by saying 'within its own type/model slice,' which differentiates this tool from broader semantic list/merge operations. This is clearly more informative than the tool's title alone.

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

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

It gives a concrete workflow: 'Use returned alias IDs with update_concept_alias and similarities to assess a proposed merge.' It also warns against comparing similarities across embedding spaces or concept types. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the context is clear enough to guide correct selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds a useful behavioral trait: 'No LLM call,' indicating a cheap/fast operation. This goes beyond annotations but is not exhaustive; it doesn't mention edge cases, but given output schema and read-only annotations, it's sufficient.

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

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

Two concise sentences. The first front-loads the core purpose, the second provides routing guidance. Zero filler or redundant phrasing.

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 tool with an output schema and annotations covering safety, the description covers purpose, usage boundaries, and behavioral cost. Nothing an agent needs to correctly invoke it 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?

There are zero parameters, so the baseline is 4. The description adds context about scope ('organization-wide') but no parameter-specific details are needed. Schema coverage is trivially 100% with no properties.

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 'Read' and a clear resource: organization-wide record totals, success rate, tokens, and cost summary. Explicitly contrasts with sibling tools like list_records and benchmark tools, making its distinct 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?

Directly tells the agent when to use this tool vs alternatives: use for organization-wide stats, use list_records(job_id=...) for a specific run, and benchmark tools for comparative scores. This is explicit and 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?

Excellent disclosure that opening the thread marks it read and thereby clears it from threads_with_unread_admin_reply — this is exactly the side effect that explains why readOnlyHint is false on an otherwise read-shaped tool. It also discloses the authorization model (ownership check, admin override) and points to a docs guide, adding real value beyond 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 tight sentences, zero filler: what you get, what it changes, how to continue. The side-effect disclosure is placed before the escalation path, so nothing important is buried.

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 an output schema present, the description needn't describe return shapes, and it still covers the two things an agent cannot learn from schema or annotations: the unread-clearing side effect and the ownership scoping. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the property description already says it is the thread id as ask_support returned it, so the description's 'Continue the thread with ask_support(conversation_id=...)' mostly echoes structured data. Nothing new about format, validity, or error behavior for the single id parameter is 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?

States a specific verb and resource ('Read one of your support threads') and immediately specifies the payload of every turn by role (user, assistant, admin with author_name). It is clearly separable from ask_support, which the description explicitly frames as the write/continuation counterpart.

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

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

Gives explicit routing to ask_support(conversation_id=...) for continuing the thread, and states the access condition under which the tool fails (not found unless the thread is yours; a system admin reads any thread). It never names list_support_conversations as the way to obtain an id, so one alternative is left implicit.

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

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

Beyond annotations, the description discloses key side effects and runtime behavior: minting creates misses, resolution can invoke embeddings and the identity judge even in report mode, and embedding_model can initialize a new type. This adds material context about permissions, side effects, and model coupling that annotations alone would not convey.

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

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

The description is dense but every sentence earns its place: scope, modes, permissions, side-effect warnings, embedding restrictions, and return summary are all covered in six sentences. It is front-loaded with the core action and mode distinction.

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 an output schema, the description need not explain return shapes; it already says 'returns per-text outcomes.' Combined with permission details, mode distinctions, embedding caveats, and a docs link, an agent has what it needs to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains the mint flag's outcome modes, describes embedding_model as a composite key used only for new types, and clarifies that a type's vocabulary cannot switch embedding spaces. This goes beyond the schema's field-level 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 a specific verb and resource: 'Resolve 1..1000 texts against one concept type.' It clearly distinguishes this bulk-resolution/minting tool from sibling tools like add_semantic_concept by emphasizing range, concept-type scoping, and optional minting behavior.

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

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

The description gives explicit mode guidance: mint=false is report-only, mint=true creates misses and requires owner, reporting requires editor. It also states a clear exclusion ('existing types cannot switch spaces through import') and advises reviewing would_mint rows before authorizing creation. It does not name alternative tools directly, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by stating 'No LLM call' – a behavioral detail not in annotations – and provides a lifecycle reference ('enricher://docs/model-benchmark') that hints at operational context. This is beyond what structured fields provide, though not extensive.

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

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

The description is two sentences, with the core action front-loaded ('List compact benchmark scenario summaries and total'). It includes sibling routing and a documentation pointer without excess. Every sentence earns its place; nothing is wasted.

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 zero parameters and an output schema, the description covers purpose, usage, alternatives, and behavior. It even points to lifecycle documentation. An agent can confidently invoke this tool based on the description alone, with no missing critical details.

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

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

The tool has zero parameters, so the input schema is empty. The baseline for 0 params is 4. The description doesn't need to explain parameters; it instead mentions the output ('summaries and total'), which is appropriate. No redundancy with the schema.

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

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

The description states a specific verb and resource: 'List compact benchmark scenario summaries and total.' It clearly distinguishes from siblings by mentioning alternatives (get_benchmark_scenario and create_benchmark_scenario) and defines the scope (scenarios test enrichment, sample generation or schema generation). This is precise and immediately tells the agent what the tool does.

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

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

It provides clear routing: 'Read one with get_benchmark_scenario or create one with create_benchmark_scenario,' which tells the agent when to use alternatives. It also notes 'No LLM call,' implying it's a lightweight operation. However, it doesn't explicitly state conditions like 'when you need detailed info, use get...' but the guidance is clear enough. The lifecycle reference adds context for when to consult documentation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: 'No LLM call,' the caveat that pending zero is not proof of healthy delivery, the note that delivery is performed by the user's sync client for PostgreSQL/MySQL/SQLite, and a pointer to documentation. This gives the agent a realistic model of what the operation does and its limitations.

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 yet information-dense: it lists the resource scope, return contents, a critical caveat, routing to alternatives, delivery model, and a docs reference. Every sentence earns its place, and the most important scoping information is front-loaded before caveats and alternatives.

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 an output schema present, the description does not need to explain return values in depth. It covers operational context, caveats, sibling routing, and delivery behavior. For a read-only list operation with one required parameter, nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and the single parameter schema_id is already described as 'Saved schema UUID.' The description reinforces this by saying 'a saved schema's...' but does not add new semantic detail such as formats, defaults, or relationship to other identifiers. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 a saved schema's database registrations, linked schemas, options and sync hosts.' It enumerates the exact returned data and distinguishes itself from sibling tools by naming list_entity_states and get_record as alternatives. An agent can clearly identify what this tool does and what it does not do.

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 routing guidance: 'Use list_entity_states for server-side rows and get_record for per-record delivery state.' It also warns when not to rely on a single signal ('Pending zero alone does not prove healthy delivery') and directs to check quarantine and migration blockers. This is strong when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds that the tool requires editor permissions and incurs no LLM call cost. It also discloses that server-side state does not prove the external replica has applied deltas, and that purge_entity_state may have removed delivered rows. These are behavioral caveats not captured in annotations.

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

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

Three sentences, each carrying distinct information: purpose, requirements/returns, and caveats/routing. The most important scoping ('not per-run records') is front-loaded. No filler or redundancy.

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

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

The description covers purpose, prerequisites, return contents, pagination, edge cases (rejected/purged rows), and explicitly routes to alternative tools for diagnostics. With an output schema present, it need not detail the response structure further. It is complete for an agent to decide when and how 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?

The schema already documents schema_id, entity_type, and include_payload with descriptions, covering 60% of parameters. The description adds only that pagination uses limit/offset and that include_payload can be set false for a compact listing, which largely mirrors the schema. For the undocumented limit and offset, their purpose is evident from names and defaults, so the description adds limited additional value.

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 lists a schema's current merged entity rows, explicitly distinguishing it from per-run records. It names the returned fields (identities, revision, last_record_id, optional payload) and pagination, making the tool's purpose specific and 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?

It explicitly says to use get_record and list_database_syncs for delivery and rejection diagnostics, routing the agent away from this tool for those purposes. It also notes that rejected entities have no row and that purge_entity_state may remove rows, which informs when to expect data. The requirement for editor and no LLM call are stated.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds important behavioral semantics: is_available does not guarantee quota or every tool/media combination, missing capability flags mean unsupported on this discovery surface, default_models_web_search is search-only, Auto accounts for attachment capabilities, and no LLM call is made. These caveats materially affect how an agent interprets results and costs.

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 enumeration, then use cases, then disambiguation caveats. It is longer than many tool descriptions, but each sentence adds distinct value; only the trailing doc-link and model-selection aside are auxiliary, keeping it appropriately sized rather than padded.

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 discovery tool, the description covers purpose, when to call, interpretation pitfalls, auto behavior, behavior (no LLM call), and a documentation pointer. With an output schema present, an agent has everything it needs to decide whether and how to invoke the tool.

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

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

The tool accepts no parameters, so the schema has nothing to document; the description's field-level detail relates to output semantics rather than inputs. Per the 0-parameter baseline, no additional parameter meaning is required.

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

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

The description starts with a specific verb and resource — 'List available model keys, nominal capabilities, languages, strategies, auto-selected defaults and organization profile_limits' — making the tool's scope unmistakable. The detailed enumeration also distinguishes it from sibling list_* tools such as list_schemas and list_records without needing to name them.

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

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

It explicitly states when to use the tool ('when choosing explicit models or checking plan limits') and when not to ('ordinary calls may omit models or use auto without fetching this large catalogue'). This gives an agent a clear decision rule for invoking 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 and destructiveHint=false. The description adds extra behavioral context: 'No LLM call' (performance), 'most recent first' (ordering), the note that both per-model enrichment and arbitration records may exist for one entity, and the pagination advice. These go beyond annotation coverage and add value without 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?

Four sentences, each earning its place. The core purpose is front-loaded, then filters, then alternatives, then a practical pagination note. No fluff or redundancy.

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

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

Complete for a read-only list tool: output schema exists, annotations cover safety, and the description covers usage alternatives, ordering, pagination, and the multi-record nuance. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 71%, so baseline is 3. The description lists the filterable parameters (job_id, type, success, model, search) but only summarizes them without adding new semantics; it does not mention page or page_size, though the schema already documents defaults and constraints. No significant value added beyond schema.

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

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

States a specific verb (list) and resource (records) with clear modifiers: 'compact, paginated records in your organization, most recent first.' It also differentiates from siblings by explicitly naming get_record and list_entity_states, making the tool's scope unambiguous.

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

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

Provides explicit when-to-use guidance: 'Filter by job_id to retrieve persisted outputs of an asynchronous workflow' and directly points to alternatives: 'Use get_record for full output and failures; use list_entity_states for current merged entity state instead of run history.' Also advises on pagination: 'Fetch every page when a job produces more than one page of records.' No gaps.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: pinned ordering, compact summary format with IDs/names/links, and the notable 'no LLM call' trait. It also warns about unpublished changes in working copies, which is valuable beyond 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 sentences, each earning its place: the first states the core action and output, the second routes to sibling tools, and the third provides a caveat about published vs. working copies. 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?

Given that the tool has no parameters, has an output schema, and is covered by safety annotations, the description is complete. It explains what is returned, how results are ordered, and the key caveat about database-linked schemas, leaving nothing essential for the agent to guess.

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

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

The tool has zero parameters, so there is no parameter semantics to document. Per the baseline for 0-parameter tools, this is adequate; the description appropriately focuses on output and usage rather than parameter details.

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: 'List saved schemas in your organization, pinned first.' It also clarifies the output is compact summaries with IDs, names, and links, and distinguishes itself from get_schema and get_schema_part, so an agent can tell it apart from related 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 alternatives and the conditions for choosing them: 'Use get_schema to inspect a chosen schema and its input contract, or get_schema_part for a targeted edit.' It also adds practical guidance about enriching database-linked schemas against the published version rather than the working copy.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: 'No LLM call' (performance hint), the comparability constraint across concept_type/embedding_model slices, and the specific semantics of 'review' view. These go beyond what annotations state, so a 4 is warranted.

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 five sentences, front-loaded with the core purpose and key constraints. It avoids fluff and includes a useful doc link. It is appropriately concise for the complexity, though it could be slightly more structured by separating the review-view note, but overall it's efficient.

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

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

For a listing tool with an output schema, the description covers the essential decisions: the two views, the alternative for detail, the comparability caveat, and the read-only nature. It does not explicitly mention pagination behavior, but the schema provides limits/offsets and the output schema covers return structure. The review-view distinction is important and well stated. Overall, nothing critical is missing.

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

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

Schema coverage is 63%, so the description should compensate for undocumented parameters (limit, offset, sort_order). It does hint at filtering via 'usage counts' and 'type/model facets', which maps to min_ref_count and concept_types, but it does not clarify pagination or sort semantics. Since the schema already documents the key params (view, search, concept_types, min_ref_count, sort_by), the description adds only marginal value, so a baseline 3 is appropriate.

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 ('Browse') and resource ('organization concepts') and enumerates the key facets returned (aliases, usage counts, type/model). It explicitly differentiates from the sibling get_semantic_concept by directing users there for details and neighbors, so an agent can immediately tell this is the list operation.

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

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

It clearly names the alternative tool (get_semantic_concept) and the condition that selects it (when details/neighbors are needed). It also explains the two view modes, including the special 'review' behavior, which helps the agent choose the right view. The pointer to documentation adds further context for when this tool is appropriate for vocabulary review.

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 this is a safe read-only operation, but the description adds useful behavioral details: results are ordered by newest activity first and include message_count and unread_for_user. It does not discuss limits or pagination, but the output schema likely covers return structure.

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: it states what is returned, the ordering, key fields, and the primary use case. Every sentence contributes 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?

Given that this is a zero-parameter read-only listing tool with an output schema and clear annotations, the description provides sufficient context. It explains ordering, included fields, and the primary follow-up action.

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

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

The tool has zero parameters, so there is no parameter semantics to disambiguate. The baseline for zero-parameter tools is 4.

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: lists the user's support threads. It also distinguishes the tool's role from read/continue tools by framing it as the way to find a conversation_id, so an agent can identify it 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 clearly states when to use the tool: to find the conversation_id of an earlier thread to continue or read, including threads opened in another session. It does not explicitly name alternatives or exclusions, but the intended usage context 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 destructive/open-world annotations, the description discloses overwrite behavior, returned fields, conflict inspection, arbiter failure fallback, LLM cost implications, pending-request behavior, and blocking behavior for rule-based merges. These are substantive operational details not already covered by 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 purpose and key constraints are front-loaded, and the length is justified by the tool's complexity. However, the description is dense and somewhat run-on in places, with several clauses that could be split for easier scanning.

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

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

Given the complexity, annotations, and output schema, the description is complete enough for correct invocation. It covers destructive overwrite risk, arbitration delegation, fallback behavior, and the fact that callers should inspect warnings and fusion method.

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 all five parameters. The description still adds useful semantics, especially how arbitration_model='auto' interacts with use_platform_models and how rule-based merges block without a model call.

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: "Fuse two or more records of the same entity into a new arbitration record." It also explicitly bounds the scope with "not to merge different entities," which distinguishes it from merging unrelated records or concepts.

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 to use the tool ("after separately recovered model runs") and when not to use it ("not to merge different entities"). It also distinguishes the rule-based path from the arbitration-model path and explains the arbitration delegation behavior, giving clear selection 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 indicate destructiveHint=true and readOnlyHint=false, which the description complements by detailing side effects: impact_only=false rewrites aliases, entity identities, referencing payloads, and queues convergence. It also discloses 'No LLM call' and warns that similarity alone does not establish identity, adding important behavioral context beyond the structured annotations.

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

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

The description is compact and well-structured: it opens with the core action, then explains default behavior, conditional behavior, prerequisites, and output. Every sentence contributes essential information with no redundancy, making it easy for an agent to parse quickly.

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

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

For a destructive, two-phase operation, the description covers all necessary aspects: default safety mode, owner requirement, consequences (alias/identity rewrites, convergence queueing), non-LLM nature, prerequisite evidence checks, and output type. It references documentation and related tools, ensuring an agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by elaborating on impact_only's dual semantics (impact reporting vs. actual merge with owner requirement) and the consequences of each mode, going beyond the schema's brief descriptions. It doesn't add new info for winner_id/loser_id, but the mode explanation justifies a score above baseline.

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

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

The description clearly states the action: 'Merge a loser concept into a winner.' It distinguishes two operational modes (impact_only true/false) and explicitly notes that similarity alone is insufficient, implying this is an identity-based merge rather than a fuzzy match. This separates it from sibling tools like merge_records or update_concept_alias.

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

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

It provides explicit when-to-use guidance: defaults to impact_only=true for inspecting counts and affected replicas before approval, while impact_only=false requires owner role. It also advises inspecting get_semantic_concept and judge review evidence first, and points to enricher://docs/semantic-ids for further details. No ambiguity about prerequisites or modes.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries the burden of behavioral disclosure. It discloses that start launches billed background re-embedding, continues enrichment, and switches slices after coverage, plus the limitation that cancel does not guarantee interruption. It also notes owner permissions and cost preview, which are not in annotations.

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

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

The description is dense but every sentence adds value: purpose, permission requirements, action-specific guidance, parameter requirements, and behavioral caveats. It front-loads the purpose and organizes details logically, making it efficient for an agent to parse.

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 an output schema present and a complex multi-action tool, the description covers permissions, parameter requirements, side effects, and limitations. It leaves no obvious gap for an agent to call it correctly, and it references documentation for deeper detail.

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 parameters are documented, but the description adds crucial conditional semantics: target_model is required for preview/start, and source_model defaults to the current space when omitted. It also clarifies that concept_types scopes the move, which is not obvious from the schema 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 clearly states the tool inspects or migrates the organization's concept embedding space, with explicit action types (status, preview, start, cancel). This distinguishes it from other tools by focusing on embedding migration specifically. No other sibling tool appears to cover this domain.

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 maps actions to permission levels: status is read-only, while preview, start, and cancel require owner. It also advises running preview before start to review cost and collisions, and clarifies that cancel does not guarantee interruption or rollback. This is actionable guidance for an agent deciding which action to invoke.

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?

Goes well beyond the destructiveHint annotation by explaining side effects (changing every usage site), automatic re-spelling behavior, refusal conditions, collisions, recursive containment, and semantic ID constraints. No contradictions with annotations.

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

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

The description is information-dense but every sentence adds operational value: purpose, prerequisites, side effects, refusal conditions, and related tool requirements. It is front-loaded with the core action and structured logically.

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

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

Given the tool's complexity, the description covers prerequisites, side effects, failure modes, related publishing requirements, and points to documentation. The output schema fills any remaining return-value expectations, making this 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?

Schema description coverage is 100%, so parameters are already documented. The description still adds meaning by explaining the destination semantics and the implications of moving into $defs.X, though it does not detail the path format beyond the schema's example.

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

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

States a specific verb ('Move one property') with precise destination options ('root, an object path or $defs.X') and key semantics ('preserving its flags and expertise'). This clearly differentiates it from sibling tools like add_schema_property and update_schema_property.

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 explicit operational guidance: requires editor, no LLM call, read source and destination with get_schema_part first, and publish_schema for database-linked schemas. It also covers when the move is refused, which is strong usage context beyond simple alternatives.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the bar is lower; the description adds real value by disclosing the dry-run-then-approve workflow, the 'no other object changes' side-effect boundary, the conditional semantic-ID assignment gates, and the fact that host_path/strip_prefix do not apply to the compact scalar form.

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 content is largely substantive, but it is delivered as one dense, run-on paragraph (~180 words) mixing preconditions, mechanics, edge cases, and modeling notes without headings or bullets, which makes it hard to parse for a long schema-rewrite operation.

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

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

An output schema exists, so return values need not be explained, and the description covers the transformation mechanics, dry-run inspection flow, permissions, and prerequisites. Coverage is strong, with only minor gaps around failure modes of the rewrite.

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 baseline is 3, but the description adds meaning beyond the schema: it defines host_path's full grammar ('' root, object path, 'path[]', '$defs.X'), explains strip_prefix's effect on moved names (product_name → name), and clarifies that both are inapplicable to the compact-scalar form.

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+resource ('Materialize an entity region from get_schema's x-entityMap') and details exactly what transformation occurs (flat members moved into a named object, pairing facts staying on the host, token stripping). It distinguishes itself from siblings like move_schema_property and add_schema_property by describing an entire region-rewrite, though it never explicitly names the alternatives 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?

It gives clear operational context: dry_run defaults to true and should be inspected before persisting with dry_run=false 'only after approval,' it requires the editor role, makes no LLM call, and notes that database-linked structural edits still require publish_schema. No explicit when-NOT-to-use exclusions are given, keeping it short of a 5.

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

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

Beyond the annotations, the description discloses that uncached resolution may invoke embeddings and the identity judge, requires editor permissions, and asserts no concept addition or usage increase. This gives a clear side-effect/cost picture without contradicting the idempotentHint/openWorldHint annotations.

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

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

The description is dense but every sentence earns its place: purpose, permission/cost, return values, usage decision, parameter caveat, and inspection advice. Key purpose is front-loaded.

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

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

Given an output schema and rich parameter descriptions, this is complete for an agent to call correctly: it explains return semantics, when to use, side effects, and the one non-obvious parameter behavior. Minor omissions like judge_floor default behavior are already in the schema, so not significant.

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 already covers 80% of parameter semantics, and the description adds meaningful guidance for embedding_model ('select the space for a new concept type, not change an existing type's space'). It also clarifies judge evidence and matched-concept behavior, going beyond the schema's basic 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 opening sentence states a specific action ('Preview identity resolution') and explicitly constrains it ('without adding a concept or increasing its usage'), distinguishing it from mutation siblings like add_semantic_concept. The output vocabulary and use of 'probe' make the tool's role unmistakable.

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

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

'Probe before adding; a matched incumbent may already represent the intended entity' is an explicit when-to-use instruction tied to the add workflow. The description also specifies the editor requirement and when embedding_model applies, so an agent can decide between this and add_semantic_concept.

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

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

Annotations already mark destructiveHint=true, and the description adds substantial behavioral context: queued migrations apply asynchronously on replicas, cross-schema conflicts remain blockers, editor permission is required, and no LLM call is made. This goes well beyond the annotation signals.

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

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

The description is dense but every clause earns its place: purpose, preconditions, permissions, validation mode, transform confirmation, language requirements, async behavior, and a docs pointer. It is front-loaded with the core purpose and does not waste words.

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

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

For a complex, destructive publish operation, the description covers prerequisites, permissions, validation paths, async replica behavior, and conflict handling. An output schema exists, so return-value details are not required in the description. A docs reference is included for the full workflow.

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?

Even though schema description coverage is 100%, the description enriches each key parameter: validate_only returns diff/blockers/warnings/migration_sql, confirm_transforms is required for user-approved transform migrations, and key_language is needed when multilingual classification requires it. This adds real decision-making value 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 opens with a specific verb and resource: 'Publish a database-linked schema's working copy as the contract used by enrichment and replicas.' It clearly distinguishes publishing from editing or saving by noting that unlinked drafts cannot be published and that a newly linked schema sends nothing until first publication.

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 strong usage context: it requires editor permission, supports a validate_only dry-run, and explains when confirm_transforms and key_language are needed. It does not explicitly name sibling tools like save_schema or update_schema as alternatives for draft editing, so it stops short of full alternative routing.

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