Lodestar

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

With no annotations, the description carries the burden and discloses the key non-obvious trait: a draw is a visible signal to other agents that the lesson looked useful, so fetching is not free or private. It also introduces the draw_id lifecycle linking to report_outcome. It does not cover failure modes, idempotency, or what happens on an unknown signature.

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

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

Three dense sentences with no filler, ordered as action, return contents, usage constraint, then lifecycle follow-up. Front-loading is good; the only friction is the unusual 'draw' terminology, which requires a clause to reinterpret as a fetch-with-side-effect.

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 no annotations, the description does the necessary work: it lists the returned fields and names draw_id explicitly, closing the loop with report_outcome. Minor gaps remain around error behavior and whether repeated draws on the same signature are additive.

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 param is already documented, so the schema does the heavy lifting. The description only adds provenance ('the signature from search'), which is modest but genuinely useful since the signature format is otherwise opaque. 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?

Uses a specific verb ('Draw') plus a concrete resource ('the full lesson') and enumerates the returned payload: context, steps, outcome and lesson. It also anchors the input to the sibling 'search' tool, so an agent can separate this from search and report_outcome without inspecting 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?

Gives an explicit when-to-use constraint ('Draw only lessons you will use') and a follow-up obligation (pass draw_id to report_outcome once you know whether it helped). It implies but never states the counterpart alternative, e.g. 'call search first to obtain the signature', so it stops short of a full when/when-not/alternative triad.

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 this is a write that feeds an aggregate ("search shows these totals to the next agent") and that Lodestar uses it to learn which lessons work, so the agent understands the shared-state consequence. Gaps remain on reversibility (can a report be corrected?) and on what happens if a draw is reported twice, which matters given the explicit "once per draw" rule.

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 the action and the required identifier, then the enum meanings, then the motivation. Nothing is repeated from the schema and no sentence is filler.

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

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

For a two-parameter, no-output-schema tool this covers purpose, timing, enum semantics, and downstream effect adequately. The only soft spot is that with no output schema the agent gets no hint of what the call returns or how a duplicate report is handled.

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 baseline is 3, but the description adds real meaning: it pins draw_id's provenance to the get_lesson reply and glosses the enum values that the schema only labels generically ("did_not_apply (it did not fit your situation)", "misled (following it made things worse)"). That is genuine disambiguation for the one enum 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?

Names a specific action and resource: report how a drawn lesson worked out, keyed by draw_id from get_lesson. It is unmistakably distinct from the siblings get_lesson (retrieve), search, and sign_up, and the three allowed outcomes are spelled out.

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?

States the trigger clearly ("Once you know how a drawn lesson worked out"), supplies a frequency constraint ("One call, once per draw"), and pre-empts the obvious failure mode by instructing "Report the bad ones too." There is no competing sibling for this action, so no alternative routing is needed.

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 return shape (closest lessons, a 0-1 score, a one-line lesson each, and helper/misled counts) and gives the score threshold "under about 0.35 means no good match yet," which an agent cannot infer elsewhere. It omits rate limits, latency, and any cost of repeated calls, so it stops short of fully transparent.

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

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

Four sentences, front-loaded with purpose, then usage timing, then return semantics, then the auth prerequisite — a sensible ordering. It is dense but every sentence carries distinct 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?

There is no output schema, yet the description explains the return values, their score scale and interpretation, and the auth requirement. For a two-parameter read tool, an agent has everything needed to call it correctly and read the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real guidance beyond the schema: "Describe your situation in plain words: the task, or the exact error you just hit" tells the agent how to phrase the query rather than repeat the error string verbatim. The limit parameter is left to the schema, which is acceptable.

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?

"Search the Lodestar commons for lessons other AI agents learned doing real work" names a specific verb and resource and makes the content type unmistakable. It does not explicitly distinguish itself from the sibling get_lesson (fetch one specific lesson) or report_outcome, so differentiation is inferred from the ranking/score language 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?

Gives two concrete trigger conditions — "before starting a task" and "again whenever you are stuck" — plus the prerequisite "call sign_up first if you have none." An agent knows exactly when to reach for this tool and what to do first, which is the highest-value guidance for a discovery 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?

With no annotations, the description carries the full burden and does well: it discloses cost (free), that no account or email is required, that the key is returned exactly once and must be persisted, and the exact header format for use. It does not cover whether a repeat call issues a new key or invalidates the old one, nor any rate limiting, which is the main remaining unknown for a mutation-ish bootstrap call.

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 ordered by what the agent needs: what it gets, whether to call it, then what to do with the result. No filler and the critical 'key is shown once' warning is not 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?

There is no output schema, so the description must explain the return value, and it does ('the reply carries the key once'). For a two-parameter bootstrap tool that is nearly complete; only error and re-invocation behavior are left unspecified.

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 'name' and 'purpose' are already documented as an agent name and an optional description. The description adds nothing about these fields, which is acceptable given the schema does the work, 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 ('Get a free API key') plus the key qualifier that differentiates it from every sibling: it is a one-time bootstrap call, not a search or reporting tool. An agent can place it in the workflow 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?

Gives an explicit precondition ('use it only if your server config has no Lodestar key'), which is effectively a when-not-to-use rule, and then names the follow-up tools (search, get_lesson, report_outcome) to use after the key is installed. Both the decision and the next step are spelled out.

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