METODIC

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write profile is known. The description adds meaningful behavioral context beyond that: debriefs accumulate and nothing is overwritten, which clarifies the append semantics that idempotentHint=false alone would leave ambiguous.

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 resource, then the content categories, then the timing instruction. No filler sentences; every clause carries selection or invocation value.

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?

Covers purpose, trigger, and accumulation semantics for a mutation tool with six parameters and no output schema. It doesn't state what the call returns or how the appended debrief is identified, a minor gap rather than a blocking one.

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's content list (how it went, what worked, what to improve, follow-ups) loosely maps to notes/went_well/to_improve/follow_ups, but adds no format, syntax, or rating 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?

Specific verb (save) + resource (debrief onto a session in Metodic) with a content breakdown (how it went, what worked, what to improve, follow-ups). No sibling tool covers debriefs, so this is clearly distinguishable from the session-design/generation 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?

Gives explicit trigger conditions: after the user has run their workshop and reported back, or after a debrief conversation, with a sequencing instruction ('synthesize first, then save'). No when-not guidance or named alternative, but no obvious alternative exists among the 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?

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, but the description adds real behavior: Metodic resolves every slug against the real library, renders one branded answer card, and silently drops anything nonexistent. A silent-drop behavior is exactly the kind of hidden trait an agent needs, though return shape and session-saving are largely delegated to 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?

Front-loaded with the core rule and heavily information-dense, with every routing line doing work. It runs long and contains a couple of restatements ('Answering a question about sessions with a list of methods is the wrong answer' repeats the preceding instruction).

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 11-parameter aggregator tool with full schema descriptions and no output schema, the description supplies the missing pieces: the lookup-first workflow, routing to siblings, and the rendering/dropping behavior. Nothing an agent needs in order to call it correctly is 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 coverage is 100%, so all 11 parameters are already documented, including the case/cases and slug/why semantics. The description only reinforces the why reasoning quality and the lookup-then-fill workflow, adding little beyond the schema's own field descriptions.

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 function — composing one branded answer card from library picks — and explicitly contrasts itself with generate_document, prose, and web search. The routing sentences naming find_session_format, search_methods, list_frameworks and search_articles make it unmistakable which sibling covers which sub-question.

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?

Explicit when/when-not plus alternatives: 'ALWAYS use this — not generate_document, not prose, not a web search — for a question about WHAT TO USE OR READ', followed by a decision table mapping question types to the lookup tool to call first. It even warns against the wrong pattern (answering a sessions question with a list of methods).

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 substantial behavior beyond annotations: it returns session_id immediately, the card back-fills in about a minute, the agent should not poll design_status unless there is no card, and it costs 2 Metodic credits. This is exactly the operational context an agent needs for a non-idempotent creating 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?

Front-loaded with the core action and outcome, then the return/cost detail. Every sentence carries operational value 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?

With no output schema, the description correctly covers the return value (session_id plus a card that fills in) and the credit cost. Combined with 100% schema coverage and non-destructive annotations, an agent has everything needed to call it 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 description coverage is 100%, so the schema already documents all ten parameters in rich detail (days, goal, duration semantics). The description adds no parameter-level meaning 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?

States a specific verb and resource ('Turn the conversation into a REAL session... a timed agenda built from the method library, saved and ready to run'), and distinguishes itself from siblings like refine_session and design_status by framing itself as the initial creation 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?

Gives clear context for use as 'the hand-off from chat to Metodic' and prescribes what to do after (offer worksheets, handouts, documents, or send to session). It doesn't explicitly contrast with alternatives like refine_session, so it stops short of full 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?

Beyond the readOnly/idempotent annotations, the description discloses both possible return states (wait instruction while generating, HTML brief when ready), an action the caller must take on the result (render as an artifact), and the cost profile (free, no credits). This is exactly the behavioral context annotations cannot convey.

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 with zero waste, front-loading the core check and then the two outcome states plus the free-cost note. 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?

No output schema exists, yet the description covers both possible responses and what to do with the successful one, so an agent has everything needed to call and handle this polling tool 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 100% and the single parameter is already documented as 'The session id design_session returned.' The description adds no format, sourcing or validation detail 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?

States a specific verb and resource ('Check whether a session started with design_session is ready'), and explicitly ties the tool to its sibling design_session so the agent can distinguish the polling tool from the session-creation tool without opening schemas.

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?

Makes the usage context clear: it is the follow-up poll to design_session, and the 'while generating it returns a wait instruction' phrasing implies it should be re-called until ready. No explicit when-not or alternative routing is given, so it stops 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the remaining burden is light. The description adds genuinely new context beyond them: the search is 'Free and instant' (no cost/latency surprise) and it enumerates what each result contains (problem solved, audience, duration, output, rationale, methodology). It does not discuss result limits or ranking, so 4 rather than 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?

Front-loaded with the imperative 'START HERE' and the trigger condition, so the most important routing information appears first. The middle sentence enumerating return fields is dense but earns its place; overall it is slightly long but free of 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 read-only discovery tool with no output schema, the description supplies the trigger, the return contents, the cost profile, and the downstream call, which is everything an agent needs to select and follow through 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 description coverage is 100%, so all four parameters including the optional audience, language, and max_duration filters are already documented in the schema. The description adds no format or syntax detail beyond noting format_slug as the handoff key, which is the expected baseline-3 situation.

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 (find) and resource (proven session format) and immediately distinguishes itself from design_session and list_frameworks by scoping to problem-driven lookup from a curated catalogue. An agent can tell exactly what this returns 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?

Explicitly instructs 'START HERE when someone describes a PROBLEM or CHALLENGE' with three concrete example phrasings, and adds a policy of preferring these formats over improvising a structure. It also names the next step and sibling to call once the user picks one (design_session with format_slug), so the routing is unambiguous.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes beyond them by disclosing the return form (branded document in chat, saved to session, replayable 1:1 to Miro), the runtime (~20-30s), the cost (0.5 credit), and the regenerate/caching behavior. It does not explain what regeneration replaces, but the added context is substantial.

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 purpose and sibling contrast, then trigger phrases and cost. It is on the long side with heavy capitalization for emphasis, but nearly every sentence carries routing or behavioral 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?

With no output schema, the description covers what an agent needs: what is produced, where it goes, cost, timing, sizing defaults, and the sibling it must not be confused with. Nothing material for correct invocation 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 schema already documents all five parameters including the enum default logic and the regenerate caveat. The description only restates the 1-based activity number and the auto-sizing rationale, adding no new syntax or format detail 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 and resource (generate the large-format wall canvas for one activity) and explicitly distinguishes itself from the sibling generate_worksheet by contrasting wall-fills-in-together vs A4-individual. An agent can route canvas vs worksheet requests 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?

Gives explicit trigger phrases (canvas, wall canvas, poster, large format, brownpaper, matrix, mapping wall), names the alternative (generate_worksheet) and the condition that separates them, and states the required input (activity number from the agenda).

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 cover the generic flag profile (not read-only, not destructive, not idempotent, closed-world). The description goes well beyond them by disclosing the ~30-60s latency, the ~2 Metodic credit cost, and the side effect that the deck is also persisted to the user's decks. Those are exactly the operational facts an agent needs before invoking a slow, credit-consuming 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?

The purpose and the visual result are front-loaded, and the operational facts (one call, latency, cost) are packed into a short trailing sentence. It is dense without being bloated, though the parenthetical card-appearance detail is slightly decorative for an agent deciding whether to call the 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?

With no output schema, the description correctly compensates by describing what the user sees (paper cards in chat, flip interaction) and what is persisted. Cost, latency, and single-call behavior round it out; only failure modes (e.g. insufficient credits) 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%, so both count and session_id are already documented in the schema, and the description adds essentially no syntax or format detail beyond them. Baseline 3 is appropriate when the schema carries the parameter burden.

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 verb (generate) and a specific resource (a METHOD CARD DECK for a session), and describes the artifact concretely: post-it colours, icon on the front, steps and tip on the back. It is clearly distinguishable from sibling generators like generate_slides or generate_worksheet by the card-deck output, though it never explicitly contrasts itself with 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 implied by 'for the session' and by naming the required session_id, so an agent can infer this is a per-session generation step. However, there is no explicit when-to-use vs. when-not, and no guidance on choosing this over generate_handout, generate_worksheet, or other sibling generators that also produce session artifacts.

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 cover the safety profile (not read-only, not idempotent, not destructive, not open-world). The description adds genuinely new traits: ~20-30s latency, ~0.5 Metodic credit cost, output returned as a branded HTML artifact and persisted to the session's Documents, plus the instruction not to author the document manually.

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 exclusion is front-loaded, which is the right ordering. However, the document-type enumeration appears twice (once as 'a pre-read, a briefing, a client brief, prep notes...' and again as 'participant PRE-READ or BRIEFING... CLIENT BRIEF... follow-up summary'), which is redundant bulk.

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, non-idempotent generation tool with no output schema, the description covers the return shape (branded HTML artifact), persistence behavior, cost, latency, and the sibling it redirects to. 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 100%, so every parameter (including the tricky 'force' redirect and the audience enum) is already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, 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+resource (generate a written document via Metodic's real document builder) and explicitly names the sibling it is not (answer_from_library). An agent can distinguish it from generate_handout/generate_slides/generate_worksheet by the 'own audience, branded document' framing.

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?

Opens with a hard exclusion ('NOT for a list of sources, methods, formats or reading'), names the alternative and its behavior, then enumerates positive use cases (pre-read, briefing, client brief, prep notes, invitation, follow-up, fill-in template). Explicit when-to-use, when-not, and alternative.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely non-derivable context — ~15-30s latency, ~0.5 Metodic credit cost, and the fact that the artifact is both returned in chat and persisted to the session. It stops short of explaining what happens on regeneration of an existing handout.

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?

Dense but front-loaded: the core distinction from a worksheet appears in the first two sentences and the operational facts (activity number, kind, latency, credit) are batched at the end. Slightly padded by 'using Metodic's real generator', which carries no selection value.

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 carries the return-value burden and does so ('branded HTML artifact in the chat, also saved to the session'). Cost, latency, required inputs, and sibling disambiguation are all present; nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3. The description adds a little beyond the schema: it notes activity is 1-based and that `kind` is optional, and its framing-activity remark implicitly widens the valid range of the `activity` parameter beyond the narrative agenda.

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 artifact ('Generate a participant HANDOUT... return it as a branded HTML artifact') and explicitly distinguishes the output from the sibling generate_worksheet ('Unlike a worksheet (which participants fill in), a handout is READING/REFERENCE material'). An agent can route correctly 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?

Gives the condition that selects this tool over the worksheet sibling and enumerates the acceptable content types (background, framework, case study, persona, checklist). It even resolves an edge case an agent would likely get wrong: framing activities (Opening/Closing) can have handouts too.

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 establish the write/non-idempotent/openWorld=false profile, and the description adds genuinely new operational context: ~40-90s runtime, ~2 Metodic credits, and that output is both shown as a chat slide viewer and persisted to the session. It does not mention that re-calling may produce a duplicate deck despite idempotentHint=false.

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 purpose and deck scope, then cost/latency facts. The long mid-sentence enumeration of deck sections is informative but heavier than needed; a small amount could be trimmed without losing routing value.

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 correctly covers the return/delivery model (chat slide viewer plus saved to session) and the cost/time budget, leaving nothing an agent needs in order to call this single-parameter tool 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?

Only one parameter (session_id) and schema description coverage is 100%, so the schema already carries the meaning. The description adds nothing about the identifier beyond 'the session's SLIDE DECK', which is the correct baseline for full schema coverage.

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 (generate) and resource (slide deck) and enumerates the exact deck contents (opening, journey, per-activity chapter, timer, breaks, questions, closing), which cleanly separates it from siblings like generate_handout, generate_worksheet, generate_canvas and generate_cards.

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 clear this is the full-deck generator ('One call makes the whole deck') and warns of cost/latency, implying it is the heavyweight option, but it never explicitly says when to pick it over generate_handout or generate_document, nor any when-not condition.

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?

Goes well past the annotations: discloses ~15-20s latency, ~0.5 Metodic credit per call, free re-fetch when a worksheet already exists, that output is a branded document returned in chat and saved to the session for the PDF, and 'do NOT author these yourself'. This is a mutation (readOnlyHint=false) so the cost/side-effect disclosure is the important part, and it is present.

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?

Dense but front-loaded: the core purpose and the sibling routing come first, then cost/latency mechanics, then the framing-activity caveat. Each sentence carries information, though the description is long enough that a reader must parse several distinct clauses.

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 still explains what comes back (a branded document in chat, persisted to the session) and covers side effects, cost, latency, and the no-worksheet edge case. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: 'activity' is 1-based from the agenda and should be incremented per activity, and 'regenerate' should only be set when a new version is explicitly wanted. It stops short of restating parameter syntax, which the schema already covers.

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 the A4 PARTICIPANT WORKSHEET for ONE activity' — and immediately contrasts it with the sibling generate_canvas ('NOT the big sheet on the wall'). An agent can distinguish this from every other generate_* sibling 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?

Explicit routing: a concrete keyword list (canvas, wall canvas, poster, brownpaper, large format, A1, A0, matrix, mapping wall) sends the caller to generate_canvas, and it explains the multi-call pattern ('call this once per activity (1, then 2, …)') plus the exclusion ('Framing activities have no worksheet').

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, and non-destructive, lowering the bar. The description adds genuinely useful behavioral context beyond them: the returned balance is the pool that generation tools spend, and for team members it is the team's shared balance, which changes how the agent should interpret the number.

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 purpose is front-loaded and the invocation condition follows immediately, so the most important facts land first.

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 input parameters and no output schema, the description carries the full burden and mostly succeeds: it names the resource, the trigger, and the interpretive nuance. It stops short of describing the shape of the answer (numeric balance, currency, team context already covered), a minor gap for a trivial read tool.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for on this dimension.

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 ('Show the user's available Metodic credits') paired with a clarifying definition of what credits are and which sibling tools consume them. It even disambiguates whose balance is returned (personal vs. team-shared), so an agent can distinguish it from the many generate_* siblings 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?

Gives an explicit trigger set: user asks about 'credits, cost, or whether they can afford a generation.' That is clear context for invocation, though it offers no when-not guidance or named alternative (largely unnecessary here since no sibling returns a balance).

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, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful non-annotation context: the output is text for the agent, not the user, plus the contents returned and a Metodic link. The contradictory 'show the session' sentence slightly blurs this.

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-loading is good, but the description contains a visibly truncated duplicate ('facili — every activity's agenda slot, method, step-by-step instructions,') and a closing sentence that repeats and contradicts the opening. These defects mean not 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?

No output schema exists, so the description must describe return values, which it does: agenda slots, methods, step-by-step instructions, facilitator tips, materials, and a Metodic link. Combined with read-only annotations this is largely complete, though the self-contradictory display sentence leaves an ambiguity about intended use.

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 there is a single required parameter (session_id) already documented in the schema. The description adds no syntax, format, or sourcing detail for session_id beyond what the schema provides, 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 (READ) and resource (a session) and explicitly distinguishes itself from the sibling session_one_pager. However, the closing line 'Use this to show a session's runnable detail' muddies the read-vs-display distinction the opening establishes, and a truncated duplicate phrase ('facili — every activity's agenda slot...') weakens an otherwise precise statement.

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 when-to-use ('before answering a follow-up') and names the alternative with its triggering condition ('To SHOW the session to the user, call session_one_pager instead'). This is strong routing guidance, but the final sentence contradicts the stated use case by telling the agent to 'show' with this tool, undercutting the exclusion.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about the content each entry carries ('what each is best for and when to use it'), but says nothing about pagination, list size, or filtering 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 no filler; the core capability (browsing frameworks and their fit) is front-loaded ahead of the usage rationale. Slightly verbose in the parenthetical list but still 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?

For a read-only browse tool with one optional param, no output schema, and annotations covering safety, the description supplies enough to call it correctly and understand the value of the results. The lack of explicit sibling differentiation (search_methods) is the only meaningful 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?

There is a single optional 'query' parameter with 100% schema description coverage, so the schema already documents filtering by name/category. The description adds no additional meaning about how the query matches, 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 (browse) and resource (learning and facilitation frameworks), reinforced by concrete named examples (Design Thinking, Liberating Structures, 4C/ID, PreMortem). It clearly conveys what the tool returns, though it does not explicitly distinguish itself from the similar sibling search_methods.

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 second sentence gives explicit usage intent: 'ground a session design in a real methodology rather than a generic structure.' This is clear when-to-use guidance, but it names no alternatives or exclusions, so the agent must infer the boundary with search_methods on its own.

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 the safe read-only, idempotent, closed-world profile, so the description need not restate safety. It adds two useful bits of context (results are 'recent' and include 'links'), but does not say how many sessions are returned, what 'recent' means, or where the links point.

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 with no filler. It is efficient, though it is also so terse that it omits details that would be cheap to include.

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 zero parameters, no output schema, and annotations covering the safety profile, the definition is nearly complete. However, the return shape ('links' to what?) and the recency window are unspecified, which an agent would want when deciding whether this tool suffices.

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 document beyond what the empty schema shows; baseline 4 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 clear verb (List) plus resource (the user's recent Metodic sessions) and scope (recent). It is distinguishable from the singular get_session sibling by 'List' and 'recent', though the description never names that alternative 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?

There is no guidance on when to use this versus get_session, search_methods, or any other sibling, and no mention of prerequisites, pagination, or limits. Usage is only implied by the word 'recent'.

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, readOnlyHint=false, idempotentHint=false and openWorldHint=false, so safety is covered; the description goes further by explaining that operations apply in order, that activity indices are 1-based positions evaluated against the agenda as it stands after earlier operations, that start/end times are recomputed automatically, that added activities receive full step-by-step method details, and that the full branded brief is returned and rendered in chat. That is substantive behavioral context beyond the structured fields.

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 critical scoping ('IN PLACE', 'existing session') and the one-call rule are front-loaded, and the operational semantics come next. The trailing sentences about returning the branded brief and editing the same session Metodic Studio shows partly restate the earlier Metodic reference, so it is slightly longer than it needs to be.

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, and the description compensates by stating exactly what comes back (the updated, branded session brief in full, rendered in the chat). Combined with the ordering semantics, automatic time recomputation, and the one-call constraint, an agent has everything needed to invoke this correctly against a 2-parameter, fully documented 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 100%, so the schema already documents the operation shapes and field meanings, giving a baseline of 3. The description adds genuine meaning beyond that by explaining the ordering semantics of the operations array and the fact that indices are resolved against the mutated agenda state, which is the subtlest part of the contract.

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 ('Modify an existing session's agenda IN PLACE') and enumerates the concrete change types (retime, rename, move, remove, update, add), which maps directly onto the operation enum. It clearly separates this from design-time creation by scoping it to an 'existing' session, so an agent can distinguish it from siblings like design_session and get_session.

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 an explicit when-to-use ('Modify an existing session's agenda'), an explicit when-not/anti-pattern ('Put EVERY change the user asked for in ONE call — a second call paints a second full session brief'), and an alternative to avoid ('Prefer this over sending the user to Metodic for an edit'). The batching instruction in particular is the kind of guidance that prevents a real agent failure mode.

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, non-open-world, idempotent and non-destructive behavior, so the bar is lowered. On top of that the description adds return shape (slug, title, summary) and a cost/latency trait ('free and instant'), plus the slug-citation workflow, which is genuine added context.

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 usage and then return/cost details. Every sentence carries distinct information 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?

Complete for a simple single-param search tool: it covers what it searches, when to prefer it over alternatives, what it returns, and downstream usage. No output schema exists, but the return fields are stated, so 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?

With a single parameter and 100% schema description coverage, the schema already documents query with examples. The description offers no additional syntax, matching rules, or semantic hints beyond what the schema provides, so 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 (search) and resource (Metodic's own published articles) and scopes it to 'facilitation, workshop design and learning'. This clearly distinguishes it from search_methods and from a generic web search, so an agent can route correctly.

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 says to use this BEFORE reaching for the open web and enumerates the triggering intents (sources, background, reading, inspiration). It also names the downstream tools where results get used (answer_from_library, session), giving both when-to-use and where-it-fits.

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 and closed-world, so the safety profile is covered. The description adds real value beyond that: the corpus size ('hundreds'), that user-saved methods are included, and that it is 'free and instant' with no side effects. Return-shape specifics are implied (timing/instructions/tips/materials) rather than detailed, which is acceptable here.

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 imperative usage rule, then filters, then a practical note. It is on the longer side for a 3-parameter search tool, but each sentence carries distinct information 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?

With no output schema, the description carries the burden of describing return content, and it does list what each method includes (timing, step-by-step instructions, facilitator tips, materials) plus saved user methods. An agent has enough to call it correctly; only pagination/result-count 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 query, category and max_duration are already documented with examples in the schema. The description's 'Filter by keyword, max duration and category' restates them without adding syntax, units or edge-case behavior, 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 verb and resource: searching a library of proven facilitation methods, with explicit scope (timing, instructions, tips, materials, plus user-saved entries). An agent can tell it apart from generation tools in the sibling list, though no sibling is named directly.

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 strong, unambiguous when-to-use rule: 'ALWAYS use this before suggesting an activity, exercise, energiser, icebreaker, ideation format, retro or workshop segment.' It also explains the rationale (recommend tested methods rather than inventing). It does not name alternatives such as find_session_format or list_frameworks or state when not to use it.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the return payload is raw HTML, the cost model is FREE (no AI, no credits), and the caller is instructed to render the result as an artifact. It stops short of covering error cases (invalid session_id) or very large sessions.

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 purpose and the artifact-rendering directive before the routing guidance and cost note. The dash-delimited list of generate_document use cases is slightly long but each item earns its place by sharpening the sibling boundary.

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 carries the return-value burden and does so: it enumerates the contents of the HTML (logo, brand colours, agenda table, activity cards) and tells the agent what to do with it. For a one-parameter read tool with full annotations, nothing an agent needs 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?

There is a single parameter with 100% schema description coverage ('The Metodic session (toolkit) id.'), so the schema already carries the meaning. The description adds no format or sourcing guidance for session_id, 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 precise verb (return) and a precisely characterized resource: a self-contained, Metodic-branded HTML one-pager containing logo, brand colours, agenda table and activity cards. It explicitly distinguishes itself from the similarly-named generate_document, so an agent can route correctly 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?

Gives explicit when-to-use ('FULL session overview: the agenda with activity detail, for the facilitator or for stakeholders who want to see the whole design') and an explicit when-to-use-the-other-tool rule naming the sibling generate_document plus the conditions that select it (participant pre-read, briefing attachment, client brief, prep notes). Nothing 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?

Annotations declare it is a non-read-only, non-destructive, non-open-world operation; the description adds genuinely new behavior by stating it returns the link, reuses an existing link rather than creating a duplicate, and discloses cost (free unless a brief is generated at ~0.5 credit). That cost and side-effect disclosure (writing a brief) is exactly the kind of context annotations cannot carry.

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 and the no-account constraint are front-loaded in the first sentence, followed by audience examples, the brief option, return value, reuse behavior, and cost in a tight sequence. It is dense but every sentence carries a distinct fact; slightly packed 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?

With five parameters, one enum, and no output schema, the definition covers return value ('Returns the link'), the free-vs-paid distinction, and link reuse, so an agent has enough to call it correctly. Remaining gaps (expiry behavior, document-id format) 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 100%, so the baseline is 3, but the description adds relational meaning beyond the schema: it explains that with_brief pairs with audience 'client' and that the resulting brief is shared alongside the plan, and that 'latest' is the default document for a client. That stitching of parameter interactions is real added value.

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 shareable link to a session') with the key scope qualifier that recipients need no Metodic account. This clearly separates it from sibling generators like session_one_pager or generate_handout, which produce artifacts rather than external access links.

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?

Names concrete use cases (client/sponsor approval, co-facilitator, participants) and notes the 'client' audience is the default and most common, which is useful routing context. It stops short of naming an alternative sibling tool or stating when not to use it, so it is clear context without explicit exclusions.

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