FactoGraph

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

Annotations already declare read-only, non-destructive, closed-world, and non-idempotent. The description adds real behavior beyond the annotations: answers stay grounded in the store's facts, claims are linked to their sources, the answer is checked against those facts, and nothing is stored. The four-state lifecycle is also disclosed. That is exactly the extra context annotations cannot express.

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

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

The description is dense and front-loaded: the core behavior comes first, then the storage guarantee, then the state enumeration. The phrasing of the state list is slightly compressed, as each state name is followed by its action, but no sentence 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 state machine description carries the return-value burden, and it does so adequately. One gap for a tool with idempotentHint=false: it does not say whether asking again creates a new step or resumes an existing one, which matters for retry decisions.

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 fully documented in the schema, including the explain-what-the-store-link-format-is detail and the default FactoGraph guide store. The description adds no parameter semantics beyond the schema, 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?

A specific verb and resource ('Ask a question' of a 'store') plus a precise behavior: the store answers only from its facts with each claim linked. The state vocabulary (waiting/running/done/failed) contrasts this tool with siblings getStep and replyToPrompt, so an agent can tell which one handles each phase.

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 names the next action for each returned state: replyToPrompt when waiting, getStep when running, follow `next` when done. That is concrete routing guidance. It stops short of stating when to avoid calling ask (for example, when a step is already in flight) and does not set any 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 only declare the generic profile (write, non-idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: nothing is persisted until the link is first opened, and the link functions as a secret key that must be handed over once and never publicized. It does not, however, warn about the consequence of calling it twice (idempotentHint=false), which is the one mutation risk an agent might hit.

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 clauses, resource stated first, then precondition, then behavior, then the secrecy warning. The colon-chained style is idiosyncratic but no sentence 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 creation tool with no output schema, the agent needs to know what it gets back and how to treat it; the description supplies both (the private link, treated as a key it must deliver and keep private). Only the repeated-call behavior is 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 coverage is 100% and the single parameter is already described, so the schema suffices. The description reinforces the parameter's intent with the consent framing ('Only after the person said yes'), adding ethical meaning rather than duplicating 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 names a specific resource (a new, empty FactoGraph store with its own private link) and clarifies that this link is what other tools accept as `store`. The creating verb is only implied by the title 'Make a store for the person' rather than stated outright, but the outcome is unambiguous. No sibling tool (ask, getManual, getStep, listFacts, replyToPrompt, startStep) overlaps with it, so differentiation is not an issue.

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?

An explicit precondition is given: 'Only after the person said yes to having one,' which matches the required `person_agreed` gate. It does not name alternatives, but none exist among the siblings, so there is little else to route to.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral content beyond that: it describes what the manual holds (fact counts, sources) and prescribes that the agent should follow it, which with no output schema is valuable.

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, front-loaded with the resource and ending with the imperative ordering rule. The em-dash asides are slightly convoluted but earn their place; 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 one-optional-param, read-only tool with no output schema, the description covers purpose, content, and usage timing adequately. It could do a bit more to contrast with listFacts/getStep for the fact-related content, but nothing essential is missing.

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

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

Schema coverage is 100% and the 'store' parameter is richly documented in the schema itself (link formats and the default FactoGraph-guide behavior). The description adds no parameter-level meaning, so 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+resource ('The store's manual') and enumerates what it contains ('how to run its steps and cite its facts', 'how many facts, from which sources'). It is clearly distinguishable from data-oriented siblings like listFacts or getStep, though it doesn't name them 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?

Gives explicit ordering guidance: 'Read it before the store's other tools, and follow it.' This tells the agent when to reach for this tool relative to all siblings. It stops short of a when-not or naming a specific alternative, so it is not a full 5.

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

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

Annotations already establish this is a read-only, idempotent, non-destructive operation, so the bar is lower. The description does add one genuinely useful behavioral fact not in the annotations or schema: the call can return either a next prompt (step is awaiting input) or a result (step is done). It does not say whether the call blocks or must be polled, nor what happens for a step that has not started.

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 clause with zero filler; the two possible outcomes are stated immediately. It is a fragment rather than a full sentence, but nothing is wasted and nothing is buried.

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

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

With no output schema, the description is the only source documenting return values, and it names the two outcomes without describing their shape or how to act on a returned prompt. For a 2-parameter read tool in a start/get/reply workflow, it is minimally adequate but leaves the agent to infer the polling and reply cycle.

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 a detailed explanation of the optional 'store' link formats and the default FactoGraph guide behavior, so the schema does the heavy lifting. The description adds no parameter meaning of its own beyond referencing 'a running step', 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 states a specific capability: retrieving the current position of a running step, specifically its next prompt or its result. That is clear and concrete, but it never contrasts itself with the closely related siblings startStep and replyToPrompt, so an agent must infer the division of labor from names 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?

The phrase 'a running step' implies the usage context (polling an in-progress step), but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing tells the agent whether to call this before or after startStep/replyToPrompt, or how often to poll.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description does not need to repeat those traits. It adds useful behavioral detail by explaining that results are numbered, each number is a link, and facts should be cited as a number plus link. It does not mention pagination or result-size behavior.

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

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

The description is two tight sentences with no wasted words. It front-loads the scope and output format, then adds the citation convention, so 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?

Given the read-only annotations, fully described single parameter, and absence of an output schema, the description is largely complete: it explains the return shape and citation format. Minor omissions such as pagination or result-size behavior keep it from being fully comprehensive.

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 sole store parameter is fully documented in the schema, including its optional default behavior. The description does not add any parameter-level meaning beyond the schema, which is acceptable at the baseline for fully described schemas.

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

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

The description clearly states the resource and result format: every fact in the store, numbered, with each number linked to the fact. The title supplies the verb "List," but the description itself does not explicitly differentiate this tool from siblings such as getManual or startStep.

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 scope (retrieve every fact) and there is explicit guidance on citing a returned fact as [F3](<link>). However, it does not state when to choose this over alternatives like getManual or ask, nor does it include exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, but the description never explains what is destructive or why repeats are not idempotent. It does add genuinely new behavioral context by describing the repeat-until-terminal loop, which annotations cannot express.

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

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

Two tight sentences with the core action front-loaded and no filler. Every clause earns its place by covering the prerequisite work and the loop exit condition.

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 looping, no-output-schema tool, the description covers the essential loop semantics and the prerequisite of doing model work first. It omits only secondary detail such as what an unsuccessful terminal state looks like or how store selection affects the call.

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 run_id, call_id, reply, and store are already documented in the schema. The description adds nothing about parameter formats beyond implying repeated `reply` calls, 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: answering the prompt a step is waiting on, which clearly differentiates it from getStep, startStep, and ask. It does not explicitly name a sibling or contrast with one, so it falls just short of a 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?

Gives clear operating context: do the model work in the step's `system` and `messages` first, and keep replying until the step is done or failed. This explains the loop condition well, but gives no guidance on when to choose this over the sibling `ask` tool.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description adds the safety gating (remove deletes only with confirm true after confirmation, add only stores approved facts) and discloses the four possible return states with their follow-up actions. It does not state idempotency or rate behavior, and it defers important detail to 'the manual'.

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 the five step kinds, and every clause carries operational weight. The sentences are long and semicolon-chained, which slightly hurts scannability, but there is 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?

No output schema exists, so the description must carry return semantics — and it does, naming all four states (waiting/running/done/failed) and the correct next action for each. Combined with the deletion and confirmation rules, an agent has what it needs to call and follow up correctly, with only minor gaps around error and limit 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?

With 67% schema coverage the schema already documents most body fields, but the description supplies the cross-parameter workflow the schema cannot express: proposal_id and confirmation come from propose's result, confirm is only valid post-confirmation, and parts must be sent in order. It adds little on `store` beyond what the schema already says about read-only public links.

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?

It names a concrete verb (start) and resource (a step in a private store) and enumerates the five step kinds it drives: propose, add, documents, ask, remove. It falls short of full sibling differentiation — notably it never disambiguates the `ask` step from the sibling tool named `ask`, which an agent could easily confuse.

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 per-step conditions: propose stores nothing, add requires propose's proposal_id plus the person's quoted reply, remove requires confirm true only after the person confirmed. It also routes follow-up calls ('call getStep' when running), though it never states when to reach for this tool versus getStep/getManual/createStore as a starting point.

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