Axiom Meridian

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

With no annotations, the description must carry the behavioral burden; it discloses the 'analyze' access level and the returned JSON keys, which is useful. However, it omits the key behavioral dependency (what happens when no prior audit_pr record exists) and does not confirm read-only versus mutating 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?

Two tight sentences with the core action front-loaded, followed by access level and return shape. Efficient and well-ordered, 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?

An output schema exists, so the return-key enumeration is somewhat redundant, and parameters are fully documented in the schema. The remaining gap is behavioral: with no annotations, the description should state the missing-audit-record case and read-only nature to be 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 the baseline is 3. The description adds only marginal value by clarifying that pr_ref/project_id must match the original audit_pr call; no format or edge-case detail beyond the schema is supplied.

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

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

States a specific verb (link/classify) and resource (PR review feedback linked to the most recent audit_pr record), and names the exact keys used for matching (pr_ref/project_id). It is distinguishable from audit_pr because it is explicitly the consumer of that record, though it does not differentiate itself from the broader query/classify 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?

Implies usage via 'for the calling LLM to classify each feedback point,' making the context inferable, but it never states when to use this versus audit_pr, query_rules, or check_feature_against_rules, nor any prerequisite that an audit_pr call must have happened first.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the dual .md + SQLite write, code assignment, in-place splicing, and declares 'Access level: write.' It stops short of stating reversibility/undo or error behavior if the proposal is not pending, so it is strong but not exhaustive.

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 action and the per-type consequences, then access level and return shape. Every sentence is informative; slightly dense but 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?

Output schema exists, yet the description usefully names the returned fields (code, scope_id, file location). Type-dependent behavior is fully covered. Minor gaps remain around failure/edge cases (e.g., approving an already-approved proposal), but it is solid for a single-param mutation.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents proposal_id. The description adds no naming/format detail beyond it, so the 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?

Specific verb+resource ('Approve a pending proposal') with a precise breakdown of what happens by type (rule/lesson get code assignment + block append + row insert; update splices in place). This clearly distinguishes it from siblings like reject_proposal, edit_proposal, and create_pending_proposal.

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

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

Usage is implied — you approve a pending proposal, and type determines the write path. However, there is no explicit when-to-use vs alternatives guidance (e.g., when to reject vs edit vs approve, or prerequisites such as the proposal must be pending). Adequate but with a clear gap.

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?

With no annotations provided, the description carries the full disclosure burden and does reasonably well: it states the tool persists an audit record (SHA-256 diff hash plus a rule-version snapshot), declares 'Access level: analyze', and enumerates the response contents. It does not state permission prerequisites or reversibility, and the stray detail="full" reference muddies the picture, but the mutation/persistence behavior is disclosed.

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

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

The purpose is front-loaded and the total length is reasonable for a tool with persistence semantics. The parenthetical '(detail="full")' and the trailing 'Returns:' line are somewhat redundant against the output schema, but there is no significant padding.

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 explaining return fields is arguably redundant rather than necessary, and the description nonetheless gives a full picture of the persist-and-return workflow. The gaps are routing guidance among siblings and the unresolved detail="full" reference, not core operational knowledge.

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 actively harms parameter understanding: it references a detail="full" mode that does not exist in the schema (only pr_diff and project_id, with additionalProperties: false), so an agent may attempt an invalid argument. It adds no meaning to the two real parameters 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 gives a specific verb+resource: audit a PR diff against a project's active rules and lessons, and clarifies it persists an audit record and returns diff/rules for the calling LLM to classify. This is clear and distinct from read-only siblings like get_rule_audit_log, though it never names a sibling or explicitly states how it differs from close neighbors such as check_feature_against_rules or analyze_pr_feedback.

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

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

Usage is only implied: the workflow (persist a record, then hand rules/diff to the LLM for classification) tells an agent roughly what the call accomplishes. There is no explicit when-to-use vs. when-not guidance and no routing to alternatives such as check_feature_against_rules for a simple single-check, which matters given ~25 siblings.

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

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

With no annotations, the description carries the full burden and does well: it discloses the write side effect (persisting a planning_checks record), the access level ('analyze'), and that the tool returns context for the calling LLM rather than a verdict. It does not cover idempotency or whether repeated checks duplicate records, but the key side effect is surfaced.

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 in the first sentence, followed by compact labeled 'Access level' and 'Returns' lines. Efficient overall, though the stray '(detail="full")' aside is dead weight that does not correspond to any parameter.

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?

Both parameters are schema-covered and an output schema exists, yet the description still usefully names the returned JSON fields. The remaining gap is the undocumented/mismatched 'detail' reference, which slightly undermines completeness.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema and the baseline is 3. The description actually adds a reference to a 'detail="full"' parameter that does not exist in the schema, which is mildly misleading rather than helpful.

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: check a planned feature description against a project's active rules and lessons. It is clearly distinct from pure retrieval siblings like query_rules or get_rule_context. It does not explicitly name those siblings, so it stops short of 5.

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

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

Usage is implied by 'planned feature description' and by the note that a planning_checks record is persisted before coding. However, no explicit when-to-use/when-not or routing against alternatives such as query_rules or get_rule_context is given.

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?

With no annotations, the description carries the full burden and does well: it declares write access, states it never writes .md files directly, and explains it stages for human review via approve_proposal. It omits idempotency and permission specifics, but the key unsafe-operation behavior is disclosed.

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

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

Front-loaded with the core action and constrained to a few tight sentences. The 'Returns' line is somewhat redundant given an output schema exists, but overall it is efficient and well-organized.

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 three-parameter write tool with no annotations, the description covers the essential behavioral traits (staging, no direct write, access level) and an output schema covers return values. Minor gaps in permission and error behavior remain.

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's mention of 'best-effort scope inference' essentially restates the default_scope_id fallback already described in the schema, adding little beyond the structured field.

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 (convert) and resource (legacy markdown file) with a clear output form (atomic-format pending_proposals, one per legacy block). It is distinguishable from siblings like index_rules_from_markdown and create_pending_proposal because it describes batch conversion of a legacy file into staged proposals.

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

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

Usage is implied: this is for legacy (###-style) markdown and always stages rather than writing. However, it never names when to prefer this over index_rules_from_markdown, extract_rules_from_transcript, or create_pending_proposal, so the agent must infer selection from context alone.

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?

With no annotations, the description carries the full burden and does so well: it discloses input normalization (private tags stripped from proposed_text and metadata), a non-obvious splitting behavior (a full rendered atomic block is split into body + metadata), scope inheritance for updates, the absence of writes to rules/lessons/.md, and the access level ('analyze'). These are exactly the side effects an agent needs before calling.

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 action and densely informative, with each sentence covering a distinct behavior. The body/metadata sentence duplicates guidance already in the schema, and the returns/access-level lines are slightly tacked on, so it is a touch redundant rather than maximally tight.

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

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

For a 9-parameter mutation-style tool with no annotations, the description covers the critical unknowns: input tampering (tag stripping), the update path's referential precondition, scope inheritance, what is NOT written to disk, and the follow-up tool. An output schema exists, so its brief return note is a bonus rather than a necessity.

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 genuine semantics beyond the schema: it explains the body-vs-metadata division and the atomic-block splitting rule that governs how proposed_text is parsed, plus the target_id prefix constraint. This meaningfully reduces ambiguity about how to populate the two primary fields.

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+resource ('Validate and persist a pending proposal') and enumerates the three types it accepts. It also draws a bright line against the sibling that actually commits changes ('Does not write to rules/lessons ... approve_proposal does that'), so an agent can place it precisely in the workflow.

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

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

The description makes the pipeline clear: this creates a pending proposal that requires human review, and approve_proposal is what promotes it. It also gives a conditional precondition (for type='update', target_id must reference an existing RN-*/LL-* id). It doesn't compare against edit_proposal/reject_proposal, but the create-vs-approve contrast is well established.

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?

With no annotations, the description carries the burden and does well: it discloses write access, that directories and a placeholder file are created (side effects beyond a pure record insert), and what the response contains. It stops short of stating what happens on a duplicate project_id or whether an existing scope/file is overwritten, which is the main residual risk for a mutation tool.

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, two compact sentences with concrete detail and zero filler. The trailing 'Returns:' line is mild redundancy given an output schema exists, but it is short enough not to hurt.

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 resource-creating tool with 100% schema coverage and an output schema, the description covers purpose, side effects, access level, and return shape. The remaining gap is conflict/idempotency behavior on repeat calls, which an agent would benefit from knowing since no annotations cover it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the 'project-<id>' derivation and the parent_scope hierarchy idea, which the schema already documents, so it adds little semantic value beyond the structured fields.

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

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

The description names a specific verb and resource ('Create a new project scope and its knowledge base directories') and enumerates the exact artifacts produced ('project-<id>' scope, knowledge-base/projects/, lessons/projects/, placeholder rules .md). No sibling tool creates a project scope, so an agent can distinguish this from create_pending_proposal or generate_project_skills 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?

Usage is only implied: the description makes clear this bootstraps a new project's scope and directories, but never states when to call it rather than generate_project_skills or create_pending_proposal, nor any precondition (e.g., that parent_scope must already exist). Adequate minimum-viable context, no explicit routing or exclusions.

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

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

With no annotations, the description carries the full burden and does well: it discloses that only a pending_proposals row is created, that there is 'no immediate effect', that approve_proposal is required after human review, and states the access level (analyze). It omits whether the proposal can be withdrawn or reversed (e.g., via reject_proposal), leaving a small gap for a mutation tool with zero annotation coverage.

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

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

Three tightly written sentences that are front-loaded with the core action and differentiation, followed by the side-effect disclosure and return value. No filler; every sentence earns its place.

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

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

For an unannotated mutation tool this is complete: it covers the action, differentiation from siblings, side-effect behavior, follow-up approval step, access level, and even names the return value. 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 schema already documents all three parameters including the RN-*/LL-* id format and the optional superseded_by. The description's note that it 'accepts both RN-* and LL-* ids' largely restates schema content, so baseline 3 is appropriate with the schema doing 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?

States a specific verb and resource ('Create a proposal to deprecate a rule or lesson') and immediately distinguishes itself from the sibling 'promote_rule' by noting it does not change scope. An agent can tell exactly what this tool produces and how it differs from its nearest alternative without opening either 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?

Explicitly names the alternative ('unlike promote_rule') and the condition that separates them (deprecate on its own vs. changing scope). It also routes the agent through the workflow by stating that 'approve_proposal performs the actual deprecation after human review', so the when-to-use and what-happens-next path is fully 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?

With no annotations, the description carries the full burden. It usefully discloses the write access level and that the mutation preserves the 'pending' status (a non-obvious lifecycle guarantee). However, it omits permission requirements, behavior on non-pending proposals, and whether edits are recoverable.

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?

Tight and front-loaded: the core purpose leads, followed by access level and return shape in compact lines. The 'Returns' sentence is redundant given the output schema exists, costing a small amount of economy but no clarity.

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 3-parameter mutation tool with an output schema (so return values need no explanation) and a fully documented schema, the description covers purpose, scope, and access adequately. Remaining gaps are behavioral details (failure on resolved proposals, permission granularity) rather than anything blocking correct invocation.

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

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

Schema coverage is 100%, so the schema already documents new_text and metadata, establishing a baseline of 3. The description adds little beyond restating the fields, and actually refers to 'proposed_text' while the parameter is named 'new_text', a mild naming mismatch that could cause confusion.

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 ('Update the proposed_text and/or metadata of a still-pending proposal') and adds the important scoping fact that status stays 'pending'. It distinguishes itself from siblings by being the only editor of an existing proposal, though it never names create/approve/reject_proposal to sharpen the boundary.

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

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

The phrase 'still-pending proposal' implicitly conveys when this tool applies (and that approved/rejected proposals are out of scope), but there is no explicit when-to-use statement, no named alternative, and no guidance on what happens if the proposal is already resolved.

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?

With no annotations, the description carries the full burden and mostly discharges it: it declares the access level (analyze), states that it has no side effects (creates no proposal), and names the returned payload fields. It does not discuss auth requirements or any limits, but for a read-only prep tool this is solid disclosure.

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

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

Purpose is front-loaded and readable, but the return fields are listed twice: once in prose ('the clean text, the project's scope chain... existing lessons... template') and again in the 'Returns: JSON with clean_text, scopes, existing_lessons, template' line. Since an output schema already exists, that second enumeration is largely redundant.

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

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

For a 2-parameter prep tool with an output schema present, the description covers purpose, side-effect status, access level, and the follow-up call, which is enough for correct invocation. The only shortfall is minor redundancy rather than a missing piece.

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 both parameters (text, project_id) are already documented in the schema. The description only echoes this at a high level ('clean text', 'project's scope chain'), adding no syntax or format detail beyond the structured fields. 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?

States a specific verb (return/extract) and resource (candidate lessons from a transcript) and enumerates exactly what it provides: clean text, scope chain, existing lessons, template. It also positions itself against the sibling create_pending_proposal, so the agent can separate this read/prep step from the write step.

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 notes it 'does not itself create any proposal — call create_pending_proposal per candidate,' which clarifies the workflow and the alternative. It lacks an explicit statement of when this should be preferred over the parallel extract_rules_from_transcript, leaving that inference to the reader.

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?

With no annotations, the description carries the burden and does so well: it declares the access level ('analyze'), states that no proposal is created (no mutation side effect), and lists the returned fields plus an instruction_for_client. It stops short of describing error or size/rate behavior, but the safety profile is clear.

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 return contract, then the crucial non-mutation caveat and the access level. Slightly repetitive in listing returns twice (prose and field list), but nothing is wasteful or confusing.

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 summarizes the payload and adds the access level and the 'no proposal created' caveat, which the schema cannot convey. 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 description coverage is 100% and both params are documented there (private tag stripping, project_id resolving scopes). The description adds little beyond restating those, so 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?

States a specific verb (extract) and resource (candidate rules from a transcript) and enumerates exactly what it returns (clean text, scope chain, existing rules, template). It is clearly distinguishable from the sibling extract_lessons_from_transcript.

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 scopes the tool's job ('Does not itself create any proposal') and names the follow-up alternative ('call create_pending_proposal per candidate'), so the agent knows both when to use this and what to do next.

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?

With no annotations, the description carries the full burden and handles it well: it declares 'Access level: write', describes the success payload shape (processed/skipped/errors counts, duration_seconds), and discloses the specific failure mode RAG_NOT_INSTALLED when the rag extra is missing. It stops short of idempotency/concurrency or auth details, so it is strong but not exhaustive.

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

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

Two compact paragraphs: the core behavior and its incremental nature come first, followed by the access/returns/error block. No filler sentences and no repetition of the schema.

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

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

For a single-optional-parameter write tool with an output schema already present, the description supplies the essentials an agent needs: write semantics, backfill-only scope, and the RAG_NOT_INSTALLED error path. Only marginal items (permissions, whether re-runs are safe) are absent.

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% for the single scope_id parameter, and the description's 'omit to process every scope' simply restates the schema's own default semantics. Baseline 3 is appropriate since the schema does the work.

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 or update ChromaDB embeddings') plus a precise scope qualifier ('active rules/lessons whose embedding_id is still NULL'). The phrase 'an incremental backfill, not a full re-embed' cleanly separates it from sibling index_rules_from_markdown / index_lessons_from_markdown, which an agent could otherwise confuse with it.

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

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

Gives a clear triggering condition: run only for records with NULL embedding_id, i.e. a backfill of missing embeddings rather than a re-index. It does not name an explicit alternative tool or state when-not to call, which keeps 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?

With no annotations, the description carries the full load and does so reasonably: it discloses write access, the concrete files created, and that AGENTS.md is modified. It does not say whether existing skill files are overwritten, whether the operation is idempotent, or what permissions are required — gaps for a mutating tool.

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 action and its outputs, then declares access level and return shape. Every sentence earns its place and 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?

Output schema exists, so the return-value sentence is somewhat redundant, but the description covers the critical unknowns for an unannotated write tool: what is written and where. Missing overwrite/idempotency behavior and the prerequisite that rules be resolved first keeps it short of a 5.

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 already documented in the schema, including the MERIDIAN_PROJECT_PATH fallback. The description only restates that output lands under project_path ('under project_path'), adding no new semantic detail beyond the schema 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?

States a specific verb and resource (generate a Claude Code skill for a project) plus the exact artifacts produced (.claude/skills/meridian/<project_id>/SKILL.md, references/rules.md, AGENTS.md). No sibling in the list produces skill files, so the agent can distinguish it immediately.

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 phrase 'from its resolved rules' implies a prerequisite (rules must already be resolved, likely via get_project_scope_resolution), but this is left to inference. There is no explicit when-to-use/when-not statement and no alternative tool is named.

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?

With no annotations, the description carries the burden but does state 'Access level: read' and describes the conditional behavior of project_id triggering scope_suggestions. For a pure read-only getter this is adequate, though it discloses nothing about output size, caching, or error 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?

Three short, front-loaded lines: purpose first, then access level, then return shape. No filler and the conditionality of scope_suggestions is stated compactly.

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-optional-param read-only tool with an output schema, the description is nearly sufficient: it names the payload keys and the conditional behavior. The only gap is the absence of routing guidance to sibling template tools, which keeps it short of a 5.

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 single project_id parameter is already documented in the schema. The description's '(if project_id given) scope_suggestions' repeats that schema text nearly verbatim rather than adding syntax or format detail, 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?

States a specific verb and resource: returns the canonical `## LL-XXX-NNN` atomic block template plus its field descriptions and usage instructions. An agent can distinguish it from get_rule_template by the 'LL-XXX' namespace, but the description never explicitly names or contrasts the sibling rule/transcription templates.

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

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

There is no when-to-use guidance. It does not say to call this before authoring a lesson, nor when to prefer it over get_rule_template or get_transcription_template. Usage must be inferred purely from the returned payload.

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?

With no annotations, the description carries the full burden and does add real value: it discloses the caching side effect, declares read access, and names the return shape (project_id + scopes list). However, it omits cache invalidation/TTL behavior, permission requirements, and whether the cache is shared or per-call, which matter for a tool whose primary action is 'cache'.

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

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

Two compact sentences, front-loaded with the core action and scope ordering, then the access level and return contract. Minimal waste, though the ADR-002 citation is a reference an agent cannot act on.

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 re-explained, and the parameter is fully covered. The remaining gap is guidance on when/why to invoke it, which leaves the definition adequate but incomplete for a non-obvious domain concept.

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 project_id parameter is fully documented in the schema (including the optional 'project-' prefix). The description adds nothing about the parameter, 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 names a specific verb ('Resolve and cache') and resource ('a project's effective scope chain'), plus the ordering ('most-specific first') and payload ('each scope's dynamic attributes'). It is distinguishable, though 'effective scope chain' and the ADR-002 reference are jargon that assumes domain knowledge, and no sibling tool overlaps this niche anyway.

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 'Access level: read' but gives no indication of when an agent should call this versus other project/rule tools, nor any prerequisite (e.g. that scopes are needed to compute effective rules). Usage is left entirely 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?

With no annotations, the description carries the full behavioral burden. It does disclose the key trait ('Access level: read') and the return shape ('events' and 'deprecated_rules'), which is genuinely useful. It says nothing about auth requirements, result size/pagination, or how far back the chronology goes.

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 lines: purpose and scope first, then access level, then return shape. No wasted words and the most important information is front-loaded. Slightly fragmented into labeled stubs rather than flowing prose, but 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?

An output schema exists, so the return-value explanation is not strictly needed, and all parameters are covered at 100%. The description adequately covers purpose, scope, and access level, but omits any sibling differentiation, which is the notable gap given the near-identical get_rule_timeline.

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 three parameters (since, scope_id, project_id) are already documented, including the precedence rule that project_id is checked before scope_id. The description adds no format or syntax beyond what the schema provides, 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?

Specific verb and resource: 'Return the chronology of rule_history changes' with a stated scope (project or scope) plus deprecated rules. The agent knows what comes back. It does not, however, differentiate itself from the sibling get_rule_timeline, which sounds highly overlapping.

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 scope ('for a project or scope') implies context, but there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as get_rule_timeline or get_rule_context. Usage is left to inference.

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

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

With no annotations provided, the description must carry the behavioral load. It usefully declares read-only access and enumerates the three output keys, but says nothing about permissions, pagination of rule_history, or behavior when a rule_id is missing. Minimal but not misleading.

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, front-loaded lines with no filler; the payload is stated first and the access level follows. The 'Returns:' line is mildly redundant against the existing output schema, which is the only slight waste.

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

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

For a one-parameter read tool with a full output schema and an output description, an agent has what it needs to invoke it correctly. The gap is routing context — nothing tells the agent when to prefer this over the overlapping rule-history and audit siblings.

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% for the single rule_id parameter, including its RN-* format, so the schema already does the work. The description adds no extra parameter semantics, which is the expected baseline when coverage is complete.

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

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

The description gives a specific verb (Return) and a concrete payload: a rule's full text, its complete rule_history, and linked lessons. That is clearly more than a restatement of the name. It does not, however, distinguish this from siblings that also surface rule metadata such as get_rule_timeline, get_rule_audit_log, or query_rules.

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

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

There is no statement of when to use this tool versus get_rule_timeline, get_rule_audit_log, or query_rules, which all touch rule data. The only usage signal is 'Access level: read', which tells the agent it is safe but not when it is the right choice.

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?

With no annotations, the description carries the full disclosure burden, and it does cover the essentials: 'Access level: read' explicitly declares the read-only nature, and it enumerates the return payload (template, fields, usage). It omits auth/permission needs, rate limits, and any failure behavior, so it is adequate but not rich.

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

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

Two short, front-loaded paragraphs: the purpose sentence comes first, followed by compact access/return metadata. Minimal waste, though the returns line partially duplicates the parameter schema.

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

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

An output schema exists, so return-value detail is not required, and the description correctly confines itself to purpose, access level, and the optional-parameter side effect. The only real gap is sibling routing among the three template getters.

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 there is only one optional parameter, so the baseline is 3. The description's note that scope_suggestions are returned 'if project_id given' merely restates the schema's own parameter description, adding no meaning beyond structured data.

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 (Return) and a precisely scoped resource: the canonical `## RN-XXX-NNN` atomic block template plus its field descriptions and usage instructions. This is clearly distinguishable from the other template getters (get_lesson_template, get_transcription_template), though the description never explicitly names them to force the distinction.

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

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

No when-to-use or when-not-to-use guidance is given. The presence of three sibling template getters means an agent must infer from the name alone which template it needs; the description does not route it or state a prerequisite (e.g., 'call before creating a rule').

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?

With no annotations, the description carries the full burden, and it does state the access level (read) and the payload characteristic that matters here (history/summary without full text). It omits operational behavior such as authorization requirements, history size limits, or truncation/pagination, which keeps it out of the top band.

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 short blocks with zero filler: the purpose and its differentiator come first, then access level and return shape. Every sentence earns its place and nothing is redundant padding.

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 full schema coverage and an existing output schema, the definition is essentially complete; return fields are even listed despite the output schema making that optional. The only minor gap is any note on history volume or truncation behavior.

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 rule_id parameter, including the RN-* format. The description adds no further parameter meaning; the baseline 3 applies when the schema does the work.

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?

Specific verb (Return) plus resource (a rule's chronological history and linked-lesson summary) with an explicit scope qualifier (without loading full text). It also names the sibling it differs from, get_rule_context, so an agent can distinguish the two without opening either 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 gives a clear comparative usage cue: pick this when full text is unnecessary, because it is 'lighter than get_rule_context.' That names the alternative and the condition that selects it. It stops short of an explicit when-not clause or any prerequisite/authorization 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?

With no annotations, the description carries the full behavioral burden and does so: it explicitly declares 'Access level: read' (substituting for readOnlyHint), explains that the tool takes no arguments, and precisely defines the staleness semantics ('stale is true only when both commits are known and differ'). It also discloses why the check matters (Python does not hot-reload), which is behavioral context an agent cannot infer from the schema.

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

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

The core action is front-loaded in the first clause, followed by the rationale and the return summary in a logical order. It is slightly longer than strictly necessary — the parenthetical about editable installs and the '(Hallazgo 7)' internal reference add length without adding decision-relevant information — but nothing is outright 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 zero-parameter, read-only introspection tool with an output schema present, the description supplies everything an agent needs: what it reports, that it is safe to call, and how to interpret the one non-obvious field. The return fields are also restated, which is redundant against the output schema but harmless and not incomplete.

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 is parameterless, so per the baseline this dimension scores 4. The description correctly reinforces that there is nothing to supply and adds no misleading parameter claims.

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 gives a specific verb and resource ('Report this running server process's version/commit') plus a second, clearly-scoped purpose (detecting stale on-disk code). It is unmistakably distinct from every sibling tool, which all deal with rules, lessons, proposals, or projects. An agent can identify this as the process-introspection tool 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 establishes the triggering context well: the tool exists to reveal the otherwise-invisible condition where an editable install was git-pulled without a server restart, and the concrete symptom it addresses ('keeps serving the old code with no other visible sign'). That is clear when-to-use guidance. It stops short of stating exclusions or alternatives (none of the siblings are related, so none are needed), keeping it at a strong 4 rather than 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?

With no annotations provided, the description carries the full behavioral burden and does disclose the most important trait explicitly: 'Access level: read', which tells the agent this is a safe, non-mutating lookup. It also sketches the return payload, though it omits anything about idempotency or side effects — acceptable for a read-only getter, but the disclosure stops short of a full behavioral profile.

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

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

Three short lines, front-loaded with the purpose, followed by access level and return shape. Every clause is short and scannable, though the 'Returns:' line restates information that the output schema already provides, which is slightly redundant.

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

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

For a one-optional-parameter read tool, the description covers what it does, the access level, and the conditional behavior tied to project_id, which is enough to invoke correctly. An output schema exists so the enumerated return contents are a minor duplication rather than a necessity.

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

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

Only one optional parameter exists and the schema already documents it at 100% coverage ('If given, also returns recommended scope_suggestions for this project'). The description repeats that schema text almost verbatim ('if project_id given) scope_suggestions'), adding no new meaning such as format or valid ID sources. Baseline 3 is appropriate when the schema does all the work.

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

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

The description names a specific verb ('Return') and a specific resource ('combined rule+lesson template guide and workflow instructions'), making it instantly distinguishable from get_rule_template and get_lesson_template via the word 'combined'. However, it does not explicitly name those siblings as the non-combined alternatives, so the differentiation is implied rather than stated.

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 phrase 'for turning a transcript into pending proposals' gives a clear purpose context but no when-to-use guidance relative to siblings like extract_rules_from_transcript, extract_lessons_from_transcript, or create_pending_proposal. There is no exclusion or ordering rule ('call this before X'), so usage is only implied.

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?

With no annotations, the description carries the full burden and largely does: it declares 'Access level: write', discloses that atomic mode upserts directly into lessons/lesson_history, and summarizes the return payload (indexed/created/updated counts, per-scope breakdown, parser warnings/errors). It stops short of stating permission requirements, conflict/replace semantics on upsert, or whether prior rows are overwritten.

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 lines, fully front-loaded: what it does, the sibling differentiation, the access level, and the return shape. No filler sentences and nothing buried at the end.

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 the description need not detail return values, and all three parameters are schema-documented. The remaining gap is operational: no mention of permissions, error/partial-failure behavior, or what an upsert does to pre-existing lesson rows in the atomic path.

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 every parameter (mode, filepath, default_scope_id) is already fully documented in the schema, including the atomic/legacy semantics. The description adds no format, syntax, or example detail beyond that, 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?

States a specific verb and resource ('Index lessons from a markdown file directly into SQLite') and explicitly contrasts with the sibling 'index_rules_from_markdown', naming the target table as the differentiator. An agent can pick between the two indexing tools without opening either 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?

Usage is implied (index lesson blocks that already live in a .md file) and the sibling comparison helps routing, but there is no explicit when-to-use/when-not guidance, and no hint about when to prefer this over transcript-based extraction such as 'extract_lessons_from_transcript'. The atomic-vs-legacy split is only explained in the 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?

With no annotations, the description carries the burden and largely meets it: it declares 'Access level: write', discloses that atomic mode updates existing rules in place (a destructive-ish upsert by code), that legacy mode never writes to rules, and lists the returned counts plus parser warnings/errors. Not covered are permissions/auth beyond the 'write' label and what happens on parse failure for the whole file.

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 purpose in one sentence, then the two modes, then access level and return shape as scannable labeled lines. There is some duplication of the schema's mode text, which is the only real waste.

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 details are not strictly required, yet the description still summarizes counts, per-scope breakdown, warnings and errors, giving an agent a full picture of a three-parameter write tool. Only file-path preconditions and failure behavior are unaddressed.

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 schema's own mode description already explains both values in detail, so the description's mode paragraph largely echoes structured data. It adds no new syntax for filepath or default_scope_id, so the 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?

States a specific verb and resource ('Index rules from a markdown file') plus the destination ('directly into SQLite'), which is more informative than a bare name restatement. It does not explicitly distinguish itself from the sibling index_lessons_from_markdown, but the rules/lessons split is self-evident from the resource named.

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 conditional guidance for the main decision point: mode='atomic' upserts canonical blocks by code while mode='legacy' stages pending_proposals instead of writing to rules. It stops short of naming alternatives such as convert_to_atomic_format or extract_rules_from_transcript, but the mode-selection context is concrete.

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?

With no annotations, the description carries the full burden, and it does disclose 'Access level: read' plus the return shape, which is genuine safety context. However, it says nothing about result limits, ordering, pagination, or whether pending review items are scoped to the caller, so important behavioral traits remain undisclosed.

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

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

Two short sentences, front-loaded with the core purpose, and no filler. The 'Returns: JSON array...' line is mildly redundant given an output schema exists, which keeps it just short of a 5.

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

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

For a zero-required-parameter read/lookup tool with a full output schema and 100% parameter coverage, the description covers purpose, scope, and filter targets. It is nearly complete; only routing to/from sibling tools 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 schema already documents type, status, and project_id semantics (including valid values). The description only restates the filter dimensions and adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb and resource ('List pending proposals for human review') and names the filterable dimensions, so an agent can separate it from siblings like create_pending_proposal or approve_proposal. It does not explicitly contrast itself with other list-type siblings (e.g. query_rules), so it stops short of full differentiation.

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

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

The 'for human review' scope and the optional filters imply when the tool is relevant, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. use query_rules for already-approved rules). Usage must be inferred.

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?

With no annotations present, the description carries the disclosure burden and does it well: it names the destructive side effect (deprecation of the original in two stores), the audit side effect (rule_history entry), the access level ('write'), and explicitly bounds the operation by saying the new-scope rule is NOT created. Remaining gaps are permission requirements and reversibility of the promotion.

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 action and its effects in the first two sentences, followed by short Access level and Returns lines. Slightly redundant since an output schema already exists, but nothing is padded or 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?

For a two-parameter mutation tool with no annotations, the description covers scope, side effects, access level, and explicitly excludes the assumed creation of the new-scope rule. The Returns line duplicates the output schema, and no guidance is given on scope validity or error conditions, so it is strong but not fully self-sufficient.

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

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

Schema description coverage is 100%, with both parameters documented as the RN-* rule id and the destination scope, so the schema already carries the semantics. The description's framing ('promote to a more general scope') adds directional context but no syntax, id format, or scope-resolution guidance 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 (promote) and resource (rule to a more general scope), then enumerates the concrete effects: original marked deprecated in both SQLite and its source .md file, and a PROMOTED rule_history entry recorded. It also preempts the most likely confusion by stating it does not create the rule in the new scope, which separates it from create_pending_proposal.

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 clear context for the operation's scope: promotion only deprecates the source rule, and creating the rule in the new scope 'requires a separate proposal' — a useful pointer toward the follow-up sibling. It does not state prerequisites explicitly (e.g. which scope relationships are valid, whether approval is needed), so it stops short of a full when/when-not map.

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?

With no annotations provided, the description carries the full burden and partially meets it by declaring 'Access level: read.' and that only 'active' lessons are returned. It stops short of disclosing pagination, result-size limits, or the STALE_INDEX caveat (which lives only in the schema), so important behavioral context is missing for a 7-param tool.

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 short paragraphs, well front-loaded: purpose first, then access level and return type. The 'Returns:' line is largely redundant given an output schema exists, but it costs little and the rest is waste-free.

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 tool with 100% schema coverage and an output schema, the description covers the scope hierarchy, both query modes, and read access — everything an agent needs to call it correctly. It omits only secondary operational details like limits, which the schema and output schema partially absorb.

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 every parameter is already documented in the schema; the baseline of 3 applies. The description echoes the query_text semantic-search trigger but adds no syntax, format, or interaction detail beyond what the schema already states.

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 (query) and resource (lessons) with scope: 'active lessons visible to a project across its full scope hierarchy (most-specific scope first)'. This distinguishes it cleanly from the sibling query_rules by resource and adds the ordering rule an agent needs.

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 explains the two operating modes — plain SQL filtering versus semantic search 'when query_text is set and embeddings exist' — which is genuine mode-selection guidance. However, it gives no guidance on when to pick query_lessons over siblings like query_rules or get_rule_context, so tool selection is left implied.

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?

With no annotations present, the description carries the full burden and does disclose meaningful behavior: 'Access level: read' establishes the safety profile, the scope-hierarchy ordering rule explains result precedence, and the embeddings-must-exist caveat explains silent fallback to SQL. It stops short of noting result caps, pagination, or performance characteristics of the semantic path.

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

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

Two sentences plus a short returns line, with the core purpose front-loaded and no filler. The 'Access level: read' and 'Returns:' fragments are slightly label-like but each carries information rather than padding.

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

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

For an 8-parameter read-only query tool with 100% schema coverage and an output schema, the description covers the essentials: purpose, scope resolution order, dual query mode, access level, and return shape. Nothing critical is missing, though the absence of any guidance tying it to its many sibling read tools leaves a small gap.

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

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

Schema description coverage is 100%, so every parameter including tags, detail, format, category, severity, query_text, and include_deprecated is already documented in the schema, often with more nuance than the description. The description's only added semantic is the query_text/SQL-vs-semantic framing, which the schema already states, 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 states a specific verb (query) and resource (active rules) plus the scope semantics ('visible to a project across its full scope hierarchy, most-specific scope first'), which is genuinely distinguishing detail. It does not, however, name or contrast with the obvious sibling query_lessons or check_feature_against_rules, so an agent must infer the boundary from the resource noun 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 implies when the tool applies (querying rules scoped to a project) and gives one conditional trigger — 'when query_text is set and embeddings exist' switches to semantic search. But it never states when to prefer this over get_rule_context, get_rule_timeline, or query_lessons, and there are no exclusions or prerequisites beyond that single mode switch.

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?

With no annotations, the description carries the full burden and does a fair job: it discloses the side-effect scope ("No side effects besides updating the record") and the access level (write). It falls short of stating reversibility, idempotency, or behavior when the proposal is already resolved.

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, front-loaded lines that lead with the action and follow with the two facts an agent most needs. The "Returns" line is mildly redundant given a full output schema exists, costing a little conciseness.

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

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

For a simple two-parameter mutation with an output schema and full schema coverage, the description supplies the key missing context: side-effect scope and access level. Return values needn't be explained since an output schema exists, though error/permission behavior is unaddressed.

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 both parameters (proposal_id and optional reason) are already documented in the schema. The description adds no syntax or constraint detail beyond that, 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?

States a specific verb and resource ("Reject a pending proposal"), which cleanly distinguishes it from the sibling approve_proposal and the broader proposal set. It's clear but does not explicitly contrast itself with approve_proposal or edit_proposal.

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 word "pending" implies a precondition (only pending proposals can be rejected), which gives implicit usage context. However, there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., use edit_proposal to change then reject), leaving guidance at the implied level.

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