The Parse

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety/scope is covered; the description's contribution is framing the content as normative ('what a contribution must meet') and mandatory reading. It does not disclose what is actually returned (no output schema exists), whether the content is static or versioned, or how long it is – a gap for a tool with no output 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?

Two sentences, both front-loaded and load-bearing: the first says what the content is, the second says when to read it. 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?

For a zero-param, read-only lookup the description is serviceable but thin: it never defines the domain vocabulary its siblings rely on ('holes', 'evidence', 'passage', 'record'), nor indicates that the returned rules govern those operations. With no output schema, a note on what the response looks like would raise this.

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 and the description correctly introduces none, so there is no parameter semantics to explain. Baseline 4 applies for a parameterless tool where nothing is left ambiguous on the input side.

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 ('the Parse') and states what the content covers: how it works and what a contribution must meet. That is specific enough to distinguish it from the action-oriented siblings (parse_submit_evidence, parse_search, parse_read_record). It stops short of saying explicitly that the tool returns the rules/spec text, leaving the agent to infer the retrieval nature.

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?

'Read before submitting' is an explicit precondition that ties this tool to the submit flow, which is real when-to-use guidance. However, it names no sibling alternative and gives no exclusions (e.g., whether it is also needed before reading a passage or searching), so routing among the other six parse_* tools is only partly 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds real value: it discloses the auth mechanism ('Authorization: Bearer <key>') and what content comes back (status plus the Architect's notes/questions). No return format or pagination detail, but with no output schema that is a minor gap.

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, with the identity of the resource front-loaded and the auth requirement second. Nothing redundant with the title or 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-parameter read tool with annotations covering safety and no output schema, the description covers purpose, auth, and returned content. Only the explicit routing against sibling tools (notably parse_submit_evidence) is missing.

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

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

Schema coverage is 100%, so the agent_key parameter is already documented, but the description goes further by giving the actual header syntax and clarifying that the key is normally sent as a header — context the schema alone does not provide.

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

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

States verb-like resource clearly: the status of your own submissions plus the Architect's notes/questions on them. Scope ('your own') separates it from the broader parse_search/parse_read_record siblings, though it never names an alternative and never says explicitly that it retrieves/lists rather than mutates.

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 by 'your own submissions' — an agent can infer this is the check-my-status tool, but there is no explicit when-to-use, no exclusion, and no pointer to parse_submit_evidence for the submission action itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context by explaining what kinds of gaps exist and that the result is meant to be picked from for research, but it does not mention ordering, pagination, limits, or what the response contains.

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

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

The description is compact and front-loads the category breakdown. It is slightly cryptic but wastes little space; 'Pick one to research' adds a small amount of useful orientation without bloat.

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 low-complexity, two-parameter, read-only listing tool, the description gives enough conceptual context to understand what open holes are. It remains incomplete on parameter behavior, especially the limit, and on return shape or ordering, which matters for an agent choosing how to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate. It partially maps the 'kind' enum values through phrases like 'registry numbers with no entry' and 'entries with no tier,' but the 'limit' parameter is entirely unmentioned and the mapping is left implicit rather than tied to the parameter name.

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

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

The description identifies the resource as 'Gaps the Parse knows it has' and enumerates three gap categories, so the broad purpose is inferable. However, it never plainly says this lists/fetches open holes, and the jargon makes the verb/resource relationship less clear than a simple 'List open gaps of type…' would.

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 usage direction is the vague 'Pick one to research,' which implies the tool returns items to choose from. There is no explicit when-to-use guidance, no mention of how this differs from siblings like parse_search or parse_read_record, and no stated preconditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The phrase 'word for word' usefully signals the content is returned verbatim and untruncated, but it says nothing about what happens with an unknown ID, size limits, or pagination for very long passages.

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 the payload shape and the ID provenance front-loaded, and no filler. It is slightly compressed into a fragment, but nothing in it is wasted.

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

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

For a one-parameter read tool with no output schema and annotations covering the safety profile, the description supplies what an agent actually needs: what is returned (full verbatim text), the identifying key, and where the key comes from. Nothing essential is missing.

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

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

Schema description coverage is 0%, so the description carries the burden — and it does: it explains that 'id' is a passage ID and, crucially, that it originates from parse_search. That is more useful than a generic type annotation. It stops short of stating the ID format or validation rules.

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 operation: retrieve the full, verbatim text of a single passage identified by ID. That distinguishes it from parse_search (which only yields IDs/snippets) and implicitly from parse_read_record. The one weak point is the term 'master', which is never defined, leaving the resource domain opaque.

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 parenthetical '(from parse_search)' is a genuine workflow hint, telling the agent the ID comes from a prior search call, so the chaining order is implied. However, there is no explicit when-to-use vs parse_read_record or parse_method, and no failure-mode guidance for bad IDs.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context by naming the returned fields and showing ID-format examples, but it does not describe behavior for missing records or other failure cases.

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

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

The description is a single tightly packed sentence with the purpose front-loaded, followed by ID examples and returned fields. Every part adds signal, and there is no wasted prose.

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

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

For a simple one-parameter read tool without an output schema, the description gives the essential return shape and ID format examples. It is nearly complete, though not-found behavior and exact ID normalization rules are omitted.

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 the meaning of the single id parameter. It does this reasonably well with concrete examples such as 'FA 1462 as fa-1462', 'REG-927', and 'sc-51', though it could be more explicit about normalization rules.

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 retrieval action and resource: reading one record by ID, and it lists the fields returned. It is clear enough to distinguish from generic search, but it does not explicitly differentiate itself from the sibling read tool parse_read_passage.

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 'by its ID' and the example IDs, suggesting the tool is used when an exact record identifier is known. However, it gives no explicit guidance on when to use this instead of parse_search or parse_read_passage.

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 the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavioral context: corpus size and the shape of results (records with tiers, passages with excerpts). This matters because there is no output schema. It doesn't touch pagination, ranking, or how limit interacts with the two result types.

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

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

Three short sentences, front-loaded with scope and result shape, with no filler. The sentence 'Returns records with their tiers and passages with excerpts' is dense but earns its place since no output schema exists; 'the master' is slightly opaque terminology.

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 and only 50% param coverage, the description should carry more weight. It covers scope and result categories but leaves the limit semantics and any ranking/ordering behavior unexplained, which an agent needs to interpret a two-type result set correctly.

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

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

Schema coverage is 50%: 'query' is documented, but 'limit' (default 8, max 20) has no schema description and the tool description never explains it — notably whether it caps records, passages, or the total, which is a real ambiguity. The quoted-phrase note does add meaning beyond the schema's terse 'Words or a quoted phrase'.

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 (Search) and resource (the whole public record, 4,700+ records plus the master's full text), and states what is returned (records with tiers, passages with excerpts). It implicitly separates itself from sibling read tools like parse_read_record and parse_read_passage, though it never names them.

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

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

Usage is only implied: searching when you don't have a specific record/passage versus reading one directly. The only explicit guidance is query syntax ('Quotation marks keep a phrase exact'), which is useful but is parameter guidance rather than when-to-use guidance. No alternatives or exclusions are 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?

Adds two things the annotations cannot express: a hard auth requirement (agent key via 'Authorization: Bearer <key>') and the key behavioral fact that submissions go to quarantine for review rather than straight into the record, which explains why destructiveHint=false despite a write. That deferred-visibility disclosure materially changes how an agent interprets the result.

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

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

Three tight sentences, with the action and auth prerequisite front-loaded. The final clause is telegraphic ('mechanism not motive') but every phrase carries content; no filler.

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

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

For a 6-parameter mutation tool with no output schema, it covers the auth path, the quarantine outcome, and evidence-quality rules. It stops short of saying what a successful call returns (a submission ID?) or how to track the review, which is the remaining gap given no output schema exists.

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

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

Schema coverage is already 83%, but the description supplies meaning for the undocumented lurking_variables parameter ('lurking variables named') and constrains content of claim/method_note ('mechanism not motive', 'primary sources by address'), going beyond the schema's terse field labels.

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: submit evidence for a hole or claim. Clearly distinguishable from read-side siblings like parse_open_holes and parse_read_record, though it does not name the closest alternative (e.g., where a submission later shows up) 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?

Usage is implied by 'for a hole or claim' and it points to parse_method for how to assemble evidence, but it never says when not to use it or which sibling to consult afterwards (parse_my_submissions), leaving the routing to inference.

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