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

The annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful context by saying it exposes capabilities, glossary definitions, field meanings, and known limits, which tells the agent what kind of reference information to expect.

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 very short, front-loads the key instruction 'Call first', and then lists the useful content categories without filler. Every element earns its place for a zero-parameter orientation tool.

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

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

For a zero-parameter, read-only describe tool with no output schema, the description is complete enough to invoke correctly and tells the agent the categories of information returned. It could be slightly more explicit about what the output looks like, but it covers the essential onboarding role.

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 and the schema fully covers them, so parameter semantics are not a meaningful differentiator here. The baseline for a zero-parameter tool 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 identifies this as a first-call orientation tool that provides capabilities, status/phase/operation glossary, field meanings, and known limits. That is clear enough to distinguish it from operational siblings like ghost_get_case or ghost_summary, though it does not explicitly say it 'returns documentation' and relies partly on the title.

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 'Call first' gives explicit usage timing relative to the sibling tools. It does not state when not to use it or name a specific alternative, so it falls short of a full when/when-not/alternatives guideline.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description is free to add value — and it does, disclosing determinism, an 8-15 line bound, markdown format, and that citations are embedded. With no output schema, this is the only place the return shape is described; only error behavior (e.g., unknown case_id) is unstated.

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, no filler. The output specification comes first and the citing directive last, both of which earn their place for a tool whose whole value is a quotable narrative.

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 read-only tool with full schema coverage and no output schema, the description covers format, length, determinism, and citation content — enough to call it and use the result correctly. The remaining gap is positioning against the very similar ghost_summary/ghost_get_case 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%, including the mask flag's effect ('mask e-mails, phones and names') and an example value for case_id. The description adds no parameter meaning beyond the schema, 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 names the resource (one decision/case) and precisely characterizes the output: a deterministic 8-15 line markdown narrative with evidence/activity citations. That is far more specific than a restatement of the title, but it never distinguishes this from ghost_summary or ghost_get_case, so an agent must guess how the narrative differs from a summary.

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 only guidance is a downstream instruction ('Quote it, do not paraphrase facts'), which governs how to consume the output, not when to call this tool. There is no statement of when to choose ghost_explain_case over ghost_summary or ghost_get_case, and no prerequisites or exclusion cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. With no output schema, the description carries the burden of describing the return payload, and it does so concretely by naming the sections returned, including the claimed-vs-verified divergence. It still omits error behavior for an unknown case_id and any size/cost characteristics.

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

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

A single dense sentence with the resource and its contents front-loaded; every clause names a distinct part of the payload rather than padding. It is a fragment rather than a complete sentence, which slightly reduces readability but not information density.

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 read tool with full schema coverage and complete annotations, the only genuine gap is the return payload, and the description enumerates it. An agent knows what it gets back and that the call is safe and idempotent; only edge-case behavior (missing case, payload size) is unstated.

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%: case_id has a format example ('case_33') and mask is documented as masking e-mails, phones and names. The description adds no further semantics about either parameter, 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 resource (one case) and enumerates exactly what the payload contains: request, subject/identifier history, resources with rule/proof/link/activity ids, planned steps, review signals, and claimed-vs-verified delta. That is far more specific than a tautology. It does not, however, distinguish itself from close siblings like ghost_explain_case or ghost_get_evidence, leaving the agent to infer 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?

There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. Usage is only implied by the breadth of the enumerated contents ('full context'), which suggests it fits when the agent needs everything about a case at once.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful behavioral context beyond those annotations by stating that a text snippet may come from the file or OCR cache and that binaries are never returned.

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

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

The definition is a single compact sentence with the return contents front-loaded and no wasted wording. The parenthetical metadata list and the binaries exclusion are both useful and efficiently placed.

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

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

For a read-only retrieval tool with no output schema, the description covers the main returned data and the no-binaries constraint. However, it does not explain the output shape, how grep/lines govern the snippet, or what happens when OCR cache is unavailable.

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 67%, with evidence_id and grep documented but lines lacking a schema description. The description adds context by saying a text snippet is returned, but it does not explicitly explain how lines or grep shape that snippet, so it only partially compensates for the remaining gap.

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

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

The description states exactly what is returned for an evidence file: metadata fields plus a text snippet, with binaries explicitly excluded. It is specific about the resource and return scope, but does not explicitly distinguish this tool from siblings such as ghost_summary or ghost_describe.

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

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

The description implies the tool is for retrieving evidence details, but it gives no explicit when-to-use guidance, exclusions, or alternatives. With several sibling tools available, the agent receives no routing help for choosing ghost_get_evidence over 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the report's scope (parse failures, ignored rows, degraded cases) and the important behavioral fact that it is empty on the shipped dataset, preventing a wasted call or a false-negative interpretation.

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

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

A single front-loaded sentence that names the report, lists its contents, and closes with the most decision-relevant fact (empty on shipped data). No filler or restatement of the title.

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

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

With no parameters, no output schema, and full annotation coverage, the description carries its share by enumerating what the report returns. A minor gap remains: it doesn't indicate the output format or explicitly position itself against ghost_review_queue, which covers the similarly-named needs_manual_review cases.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies a no-argument, no-filtering report rather than suggesting options that don't 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?

The description names the specific resource (ingestion diagnostics) and enumerates exactly what the report contains: unparsed evidence files, ignored rows/log lines, CSV issues, and cases degraded to INCOMPLETE + needs_manual_review. That content list distinguishes it from generic siblings. It stops short of a clean verb framing ('returns/reads'), but the intent 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?

The note 'Empty on the shipped dataset' is a genuine usage signal that tells an agent not to expect output in the common case. However, it does not state when to call this versus the overlapping siblings ghost_review_queue or ghost_verify_output, nor does it say whether to call it proactively or only after an ingest failure.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description contributes the row contents returned (status, risks, steps, confidence, needs_manual_review), but says nothing about ordering, pagination, or whether filters combine with AND or OR — behavior an agent would want before paging through 600 rows.

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

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

A single tight sentence pair with zero boilerplate; the return shape and the follow-up pointer are both front-loaded, and every clause carries 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?

For a 7-param filter tool with no output schema the description does name the returned columns, which is helpful. But it leaves the status/claimed distinction, filter composition, and limit default (50, max 600) unexplained, which are exactly the ambiguities the structured fields cannot resolve.

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

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

Schema coverage is only 43%, and the description adds no parameter meaning at all; it only names the return fields. Most critically, the two enum params status (COMPLETE/INCOMPLETE/NOT_APPLICABLE) and claimed (COMPLETE/PARTIALLY_COMPLETE/NOT_STARTED) are near-identical in surface form, and only the description could explain how an assessed status differs from a claimed status — it does not.

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

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

A specific verb (filter) plus resource (cases), with the returned row shape spelled out so the agent knows what it gets back. It also positions itself relative to ghost_get_case, letting an agent separate listing from fetching 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?

"Use before ghost_get_case" gives a clear sequencing rule covering the main workflow. It does not address alternatives such as ghost_review_queue for needs_manual_review=true, nor whether this is the right tool for bulk exports, so it stops short of full when/when-not 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 cover read-only, idempotent, non-destructive and closed-world, so the bar is low; the description adds real semantic context by defining what is queued and by warning that confidence_v2 is a review-priority signal, not a probability — a genuine misreading risk it pre-empts. It does not discuss volume, truncation, or empty-queue 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?

A single dense sentence with the headline concept front-loaded, then item classes, then output fields, then the confidence_v2 caveat. The parenthetical list is long but every element carries information, and nothing is 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 zero-required-param read-only list tool with full annotations and no output schema, the description conveys both what is returned and the key interpretation caveat. The remaining gaps — result shape, ordering guarantee, limit ceiling semantics — are minor and partly covered by the schema.

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 67% and the two documented params (sort, include_samples) already carry descriptions, so the schema does most of the work. The description's confidence_v2 gloss does clarify what sort='confidence_v2' means, but it says nothing about limit or how samples affect results — a baseline 3.

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 concrete artifact — a prioritised human review queue — and enumerates the item classes it contains (withheld/ambiguous links, inferred states, false COMPLETE with active risk) plus the payload fields (reasons, score, confidence_v2). An agent can distinguish it from ghost_summary or ghost_list_cases on content, though no sibling is named explicitly.

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

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

The word 'human review' implies a triage/audit use case, but there is no explicit statement of when to prefer this over ghost_list_cases or ghost_summary, and no exclusions or prerequisites. Usage is inferable 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description still adds real value by disclosing the returned analytical content, including the notable 'claimed->verified transitions (false COMPLETE)' concept an agent could not guess. It does not mention cost, aggregation window, or freshness, which keeps it below 5.

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?

One dense sentence plus a short usage clause, front-loaded with 'Portfolio view', with zero filler. The telegraphic noun-list style ('claimed->verified transitions (false COMPLETE)') is efficient but slightly cryptic without domain context.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so by naming the five categories of aggregate data returned. For a read-only, zero-required-parameter aggregate tool this is close to sufficient; only the response format and the time scope of the aggregates are left unstated.

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 include_samples is already documented with its default in the schema. The description adds nothing about that parameter, so the baseline 3 for schema-covered parameters 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 enumerates concretely what the tool returns: verified/claimed status counts, claimed->verified transitions flagged as false COMPLETE, top risk categories, violations by system, and manual-review counts. That makes the resource unmistakable and differentiates it from case-level siblings like ghost_get_case and ghost_list_cases. It falls short of 5 because there is no explicit verb and it never names the sibling it replaces for aggregate questions.

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?

'Good for dashboards and executive briefs' implies the intended consumption context, so an agent can infer this is the roll-up entry point. But there is no explicit when-not guidance and no named alternative (e.g. ghost_list_cases for per-case detail), leaving routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description usefully adds that it performs four named structural checks and computes a sha256 and status counts, but it does not disclose whether a failed validation returns a report or raises an error, which is the critical behavioral detail for a validation 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?

A single sentence with zero filler; the resource and the checks are front-loaded and the auxiliary outputs (sha256, status counts) follow compactly. 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?

With no output schema, the description must convey what comes back; it hints at sha256 and status counts but leaves the shape of validation results and failure behavior unspecified. Adequate for a simple read-only check but with a clear gap around return semantics.

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

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

There is a single optional parameter with 100% schema description coverage, including the default ('defaults to the repository output.csv'), so the schema does the heavy lifting. The description adds no path semantics beyond what the schema already states, 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 ('Structural validation') plus the exact resource (output.csv) and enumerates the checks performed (contract, vocabulary, ids, phase order) along with sha256 and status counts. It does not explicitly distinguish itself from siblings, but none of the listed siblings overlap with this artifact validation task.

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 alternatives, nor any prerequisite or exclusion guidance. The usage is only implied by the artifact name; an agent must infer that this is the pre-flight check on output.csv.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond that: the re-run is in-memory, takes roughly one second, and never writes output.csv, which is consistent with the annotations.

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

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

The definition is a single dense but front-loaded sentence that leads with the core in-memory re-run purpose and follows with outcomes and the no-write guarantee. It is appropriately sized, with only slight awkwardness from the 'and/or' 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 read-only what-if tool with two optional numeric parameters and no output schema, the description gives enough context about what results to expect: changed/manual cases and confidence_v2 human routing. It could be more complete by stating defaults or behavior for the confidence_v2 threshold, but the core call context is present.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies MIN_PICK_CONFIDENCE with a default of 0.30 and references the confidence_v2 review threshold, but it does not explicitly map the latter to min_confidence_v2 or explain its default, leaving a gap for the second parameter.

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

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

The description defines a specific what-if operation: an in-memory re-run with a different MIN_PICK_CONFIDENCE and/or confidence_v2 threshold to see which cases would change, become manual, or route to a human. It distinguishes this from tools that write outputs by stating it never writes output.csv, though it does not explicitly compare itself to sibling 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?

Usage is implied by the what-if framing: use it to simulate threshold changes and review routing without committing results. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative among the sibling tools, leaving the agent to infer boundaries.

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