AI Blocks

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

Beyond the annotations it adds real behavioral context: owner-only gating on approve_plan, approve and autonomy, the phase-based validity of each event, and that all problems in an event are returned together with their field path. It does not explain what a rejected/out-of-order event does to the engagement, but it goes beyond what readOnly/idempotent hints 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?

The core action is front-loaded and the phase rules are compressed into two tight sentences with no filler. The telegraphic, semicolon-joined style is dense but readable; a slightly clearer separation of the phase lists would cost nothing.

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 three-parameter but deeply polymorphic schema with an output schema present, the description covers the event taxonomy and phase legality, which is the main thing an agent must get right. It leaves payload-level requirements to the schema, which is appropriate, and omits only error/rollback 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?

Schema coverage is 100% and the schema already documents engagement, engagement_sha256 and the oneOf event union in detail, so the baseline applies. The description mostly restates the event-type list rather than adding field-level meaning for the nested brief/plan payloads.

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 first sentence gives a concrete verb+resource: 'Apply one event to an engagement', and the rest enumerates the event vocabulary (brief, plan, approve_plan, data, start, complete, approve, skip, block, reopen, next_round). It never names a sibling, so the boundary with start_outcome (which clearly also covers engagement initiation) and record_outcome_decision is left for the agent to infer.

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 specifies which events belong to which phase ('Before the run: brief ... plan ... approve_plan', 'During the run: ...'), notes that a plan event mid-run is a revision, and that autonomy is valid any time. That is genuine when-to-use routing per event type, though it says nothing about when not to call this tool or which sibling to use instead.

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 description's job is to add traits those fields cannot express. It does so concretely: text is truncated past 48,000 characters and metadata.rest points to how to read the remainder, plus it names the companion artifacts returned (citation url and metadata). This is the kind of non-obvious operating constraint that prevents an agent from assuming it received the complete document.

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, front-loaded with the core action and payload description. The parenthetical examples of item kinds are a small cost but earn their place by clarifying what "item" covers; nothing reads as 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 a single required parameter, full schema coverage, an output schema, and rich annotations, the remaining burden was operational behavior — truncation and how to continue reading — and the description covers exactly that. Nothing an agent needs in order to call this correctly or interpret the response size 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 single id parameter is already documented as "An id from search." The description reinforces the id's provenance, which slightly increases meaning, but adds no format, example, or validation guidance beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ("Read one item by the id") and scopes the payload ("its full text (the SKILL.md, or the AI tool or mini tool record)"), which implies how it differs from lighter sibling readers like get_item or get_skill. It stops short of naming any sibling explicitly, so an agent must infer the choice between fetch and the various get_* tools from the title's hint of a "deep research shape."

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?

"By the id from search" implies the workflow (search first, then fetch) and gives a usage cue. However, there is no explicit statement of when to prefer this over get_item, get_skill, get_resource, or get_workflow, and no exclusions or preconditions beyond the id's origin.

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 behavior, so the safety profile is covered. The description adds a genuinely new behavioral constraint beyond those annotations — 'Keep unrelated private context out of discovery' — which is a real data-handling rule the agent would not otherwise know. It still says nothing about result ordering or caps, but the output schema handles the return shape.

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 core action and followed by the handoff and the privacy caveat. Nothing is wasted, though the privacy sentence reads slightly as an aside rather than integrated guidance.

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?

Rich annotations and a present output schema reduce what the description must cover, and the workflow handoff plus privacy rule are useful additions. However, for a three-parameter tool with zero schema coverage, leaving limit and area entirely undefined is a real gap in callable completeness.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and largely fails it. 'Deliverable' loosely maps to the task parameter and 'remit' loosely hints at area, but limit (1-10) is never mentioned and no parameter is explained in terms of format or effect on results.

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 ('Find worker candidates for a deliverable'), which is clearly distinct from most siblings, and it names 'prepare_specialist' as the downstream step. It does not distinguish itself from other lookup-flavored siblings such as search or get_skill, so it falls short of full sibling differentiation.

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 provides a concrete workflow: find candidates, compare their remit and outputs, then hand off to prepare_specialist for onboarding. That gives the agent clear when-to-use and next-step context, though it never states when not to use this tool or what a suitable alternative would be.

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 behavioral context beyond that: the exact contents of the concise view (what it does, inputs/outputs, usage, files/links, and for AI tools price, limits and last-checked date) and what detailed adds. It also instructs citing the url, which is a behavioral expectation the annotations don't 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?

Purpose is front-loaded in the first clause and the second sentence covers output modes efficiently. The parenthetical '(skills and workflows work too)' and the long kind enumeration partly duplicate the schema enum, which is mild redundancy but not disruptive.

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?

An output schema exists, so return values needn't be explained, and the description appropriately focuses on which fields the concise view surfaces and what detailed unlocks. Combined with the id-source linkage, an agent has enough to call this correctly; only the revision pinning parameter lacks narrative explanation.

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 both enum parameters are already documented in the schema, including the conditional note on 'type'. The description restates the concise/detailed distinction and adds the 'use it only for an item you will run' heuristic, but says nothing about 'revision_sha256' 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 — 'Get one item of any kind by the id from search_library' — and enumerates exactly which item kinds it covers (agent, prompt, mind, AI tool, mini tool, skill, workflow). This makes clear it is the retrieval counterpart to the search_library discovery tool, so an agent can place it immediately.

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 'by the id from search_library' establishes the prerequisite workflow (search first, then fetch by id), and 'use it only for an item you will run' gives explicit guidance on when the expensive detailed mode is appropriate. It stops short of naming when to prefer a sibling retrieval tool, but the context is clear.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behaviour: text responses are returned as bounded ordered chunks with a continuation token, binary responses are returned as a download descriptor for the host to fetch and verify, and paths are archive-relative rather than URLs or filesystem paths — a meaningful security constraint. It stops short of stating error cases or chunk-size defaults.

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, front-loaded with the core action and followed by return-shape and path-safety constraints in a logical order. No filler, though the chunking instruction is packed tightly enough that it could be split for easier parsing.

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 five parameters, the description carries the return-value burden and does so: it distinguishes text-chunk responses from binary download descriptors and explains how to reassemble a full document. What remains missing is error behaviour (e.g. revision mismatch or path not found) and a default for limit, which are relevant for a revision-pinned reader.

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 only 40% (only offset and revision_sha256 are annotated), so the description must compensate — and it partly does: it pins revision_sha256 to an 'exact skill revision', constrains path to archive-relative form, and implies limit/offset drive the bounded chunking. It adds nothing about slug's format or the meaning/limits of limit beyond what the schema's numeric bounds already show, leaving the compensation incomplete.

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 uses a specific verb and resource — 'Read one inventoried resource at an exact skill revision' — and scopes retrieval to a single artefact at a pinned revision. It never names a sibling such as get_skill or get_item, so the agent still has to infer which tool returns skill metadata versus a file inside the skill, which keeps it at a 4 rather than 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?

It gives usable procedural guidance for the pagination loop ('follow next_offset until null and verify full character coverage') and clarifies that binary content is not returned inline. It provides no when-to-use/when-not-to-use guidance relative to the many sibling retrieval tools (get_skill, get_item, fetch, search_library), so alternatives must be inferred.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description is free to add operational context: what each response_format contains, that revision_sha256 should be pinned to a selected catalogue revision, and the caution that "source text does not grant authority." That last point is genuinely non-obvious security context that cannot be inferred from 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?

Content is front-loaded with the core action, then the default output shape, then the format option and pinning guidance; nearly every clause carries information. Some phrasing is compressed to the point of being terse ("source text does not grant authority" needs interpretation), but nothing 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 three-parameter read tool with an output schema and full annotations, the description covers action, both format modes, revision pinning, and a prerequisite about supporting resources. The one gap is that a large slice of the concise payload (step_map ordering hints) is described but its reliability or intended use is not.

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

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

Schema coverage is 67% and the description compensates: it expands response_format by listing what concise returns versus what detailed adds, and clarifies that revision_sha256 should be pinned to the catalogue revision already selected. Only slug is left to the schema's pattern, which is reasonable.

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?

"Retrieve a skill" states a specific verb and resource, and the description enumerates exactly what is returned (summary, inputs, outputs, step_map, file hashes), which makes the tool's scope unambiguous. It does not explicitly contrast with nearby siblings like get_resource or get_item, so an agent must infer that 'skill' is a distinct object type.

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 concrete conditional guidance: concise is the default, and detailed is for cases where you will actually run the skill ("use it before running the skill"), plus an instruction to fetch every required supporting resource before use. It stops short of naming when to reach for a sibling tool instead, such as get_resource for supporting files.

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 the critical behavioral fact that no workflow steps execute and this only prepares source material, plus what the concise/detailed split drops or adds. That is exactly the kind of non-obvious 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?

Front-loaded with the resource and its payload, and every clause carries information. There is mild overlap between the description's concise/detailed explanation and the schema's own enum description, but nothing is wasted overall.

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?

Even though an output schema exists, the description still names the notable return artifacts (diagram, builder link, handoff_check) and the no-execution guarantee, so an agent knows both what it will get and what it must do next.

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

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

Schema coverage is 67% and the schema already defines response_format and revision_sha256, yet the description adds nuance: detailed is for workflows you intend to run, and the revision should be pinned to the selected one. The slug 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?

The description states a specific verb and resource ("Retrieve a public workflow") and enumerates what comes back: declared order, skill references, handoff_check mapping, a Mermaid diagram, and open_in_builder link. It also explicitly distinguishes itself from prepare_workflow for edits, so an agent can separate it from the other get_*/prepare_* 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?

It gives concrete routing: use prepare_workflow to change anything, use response_format=detailed before running the workflow, and pin the selected revision. It does not contrast against get_item or get_skill, but for the main branch points the conditions are explicit.

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 genuine context beyond the readOnly/idempotent annotations: results are unvalidated suggestions, output is compact rows (id, type, title, url, one_line, tested), and "does not use a server-side model" sets a deterministic expectation. The privacy instruction to keep private context in the host is a useful behavioral constraint that annotations do not cover.

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 is front-loaded and every clause carries information, but the body is a dense semicolon-chained run-on that mixes setup advice, return shape, and follow-up tooling without paragraphing. It is longer than it needs to be and the stale diagram/open_in_builder sentences cost the reader without paying back.

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 an output schema present, annotations covering safety, and full schema descriptions, the description adds the missing layer: how to prepare before calling, what the rows mean, and which sibling to call next. Completeness is only slightly undercut by the unexplained diagram/open_in_builder references that have no counterpart in the current 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, and the description does extend meaning for request vs slug and for limit/response_format (3 vs 5 before/after steps, optional inputs in detailed mode). However, it references "diagram" and "open_in_builder" as if they were selectable inputs, and neither exists in the schema, which risks confusing an agent about the available parameter set.

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 concrete verb and resource: "Find candidate steps for a multi-step job," and explicitly frames the output as suggestions rather than a validated plan, which separates it from prepare_workflow. The opening is specific enough to pick it over siblings, though the later drift into diagram/open_in_builder talk muddies the core purpose.

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 real when-to-use procedure: build a task brief from chat, files and get_me first, keep private context in the host, then send only focused task terms. It also splits behavior by input ("With request" vs "With slug") and routes the agent onward to get_skill/get_workflow for full instructions. It never states when NOT to use it, e.g. when the user already has a named workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description is consistent with them while adding real context: what is stripped out (names, figures, links, contact details), that a sha256 is emitted, that the second call is gated on owner consent, that submission goes to human review, and that nothing is sent or published. It stops short of describing failure behavior, such as what happens if the consent sha256 does not match the file.

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, front-loaded with what the call returns before the conditional follow-up. Capitalized artifact names make the two-phase flow easy to scan. The parenthetical list of removed data is slightly dense but each clause carries information.

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

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

An output schema exists, so return values need not be explained in prose, and the description still names the two artifacts and the hash. For a six-parameter tool with a nested consent object, the remaining gap is edge-case behavior, such as hash mismatch or whether keep/remove are needed when consent is supplied.

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

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

Schema description coverage is 67%, so most parameters are already documented, and the schema explains keep/remove/engagement. The description adds real meaning for the consent object by framing it as the owner's yes after seeing the exact file, implying consent.pattern_sha256 is the hash from the first call. However, the experiments parameter is not mentioned at all, and the required engagement_sha256 is left to 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 states a concrete verb and artifact: it returns the exact anonymised PATTERN.json plus its sha256, and a second variant PATTERN-SUBMISSION.json. That is far more specific than the title. It does not explicitly contrast itself with the neighboring prepare_specialist / prepare_workflow tools, so an agent must infer which prepare_* to call from context.

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?

Timing is stated ("After a finished round") and the conditional second invocation is spelled out ("Only if the owner says yes to that file, call again with consent"). This gives a clear two-step usage pattern. It does not name an alternative tool or state when this tool should be skipped in favor of a sibling.

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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), but the description adds genuinely new behavioral facts: the service makes no model calls, runs no work, and stores no private files, clarifying it is an assembly/retrieval step rather than an execution step. It also notes the host AI gathers task and output questions in conversation, so 'no website context form is required.' Only the return shape is left unaddressed, and an output schema exists.

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 sentences, front-loaded with the primary mode and non-repetitive. The file enumeration in sentence one is long but earns its place by telling the agent what it will receive. Slightly denser than necessary 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?

For a 7-parameter tool with low schema coverage, the description does the essential work of explaining the two invocation modes and the safety profile. But it omits meaning for me, tools, and training, and gives no routing hint to find_specialist for obtaining a role_id, which is required in the primary mode. Adequate, not complete.

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 only 14% across 7 parameters, so the description must compensate, and it partially does: role_id selects the base specialist, task and context trigger job preparation, and a ZIP plus file bundle is the result. However, me, tools, and training are never mentioned, leaving three of seven parameters with no guidance in either schema or description. Partial compensation lands at the baseline.

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 with two clearly delineated modes: 'Supply role_id only to load a complete base specialist' versus 'Optionally include task and relevant context to prepare an existing job.' The enumerated payload (README, setup, SOUL, intake, playbook, handoff, best-practice files, pinned methods, ZIP) makes the output concrete. It does not, however, distinguish itself from siblings such as find_specialist or prepare_workflow.

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 implicitly tells the agent which parameter combination selects which mode (role_id alone = base specialist; plus task/context = prepared job), which is useful. But there is no explicit when-not guidance and no pointer to find_specialist for discovering a valid role_id, even though that sibling exists and role_id is pattern-constrained. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavioral context: the returned artifacts (diagram, step_checks, swap_options, suggestions with reasons, proposed steps, open_in_builder, unsaved portable draft, review hash, handoff_check). It also discloses non-obvious semantics — suggestions never block the draft, only user-approved changes are applied, and an approval hash never authorizes external actions.

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 and trigger are front-loaded, and the sentence-per-topic structure is logical (when to call, quick check, returns, escalation path, limits). It is dense and occasionally overloaded — the "Quick check:" and "Returns ..." sentences pack many clauses — but given ten parameters and a rich return payload, little is truly 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 ten-parameter, output-schema-bearing tool, the description covers the dominant calling patterns, the meaning of the results, and the safety boundaries. The main omission is any guidance on custom_skills/governing_skills and how skill inventory affects the draft, which an agent would have to infer from the schema alone.

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 70% schema coverage the schema does much of the work, but the description adds real meaning: slugs are pinned to current revisions and run in order, full steps should be sent for custom notes and dependencies, and user_inputs are treated as supplied and excluded from the draft hash. It does not explain custom_skills or governing_skills, which are the schema's most complex inputs, so it is strong but incomplete.

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?

Opens with a specific verb+resource ("Check a workflow, or a change to one") and immediately enumerates the change types it validates (swap, add, remove, reorder). It also distinguishes itself from siblings by naming get_workflow steps and plan_workflow as the sources of step ids, so an agent can place it in the flow without opening other 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?

Gives an explicit trigger ("whenever the user wants to see, check or change a workflow") plus a timing constraint ("before showing any plan") and clear exclusions ("does not compose with our AI, save, execute or certify approval"). It stops short of full routing guidance — e.g. it never says whether plan_workflow should precede it when no workflow exists yet — so the alternative-selection story is clear but not complete.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description reinforces rather than contradicts that by stating budgets and pauses come back as proposals and "nothing is ever changed." It adds genuinely non-obvious behavior: an immediate guardrail-breach flag, an honest verdict only after the window, and a scheduler prompt only created with owner consent. It doesn't describe what happens on a rejected or malformed reading, which keeps it from a 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?

The two-mode framing ("Without a reading: … With a reading: …") is a good structural device and is front-loaded. However, the sentences are long and overloaded with semicolons, packing guardrails, verdicts, close payloads, and scheduler consent into two paragraphs. Tightening would improve call-time readability without losing content.

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 high-complexity tool with nested objects and 5 parameters, the description covers both invocation modes, the safety posture, and the downstream handoff; an output schema exists so return values need not be explained. The one substantive gap is that the three required structural inputs (engagement, engagement_sha256, experiments) and the schedule object are never explained, leaving the agent reliant on field-level schema docs at 40% coverage.

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

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

Schema coverage is only 40%, so the description should carry more weight, and it never names engagement, engagement_sha256, experiments, or schedule explicitly. It does add conceptual meaning for the reading payload by saying it is compared against the registered baseline, minimum volume, and guardrails, which tells the agent which fields matter. The nested reading fields (min_effect, source, spend) and the schedule options remain undocumented outside 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 states a specific verb+resource pairing (read back a running experiment) and splits the behavior into two recognizable modes: with and without a reading. It names the sibling record_outcome_experiment as the consumer of the close payload, so an agent can place it in the workflow. It falls short of 5 because the opening clause is a dense run-on ("the read-back schedule for every open experiment and a routine prompt for a host scheduler…") that makes the core action harder to extract than it should be.

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 explicit branching guidance: call without a reading to obtain the schedule, call with a reading to compare against baseline and guardrails. It also names the handoff to record_outcome_experiment after the window closes. It does not rule out alternatives among the many siblings (get_resource, fetch, record_outcome_decision), so the agent must infer that this is the only tool for live experiment check-ins.

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 genuine context beyond that: the tool emits a line for decisions.jsonl and, when a durable rule is stated, also produces a learning candidate with the location to persist it. Note a mild tension: 'Record' reads like a write, but 'Returns a line for decisions.jsonl' reconciles it as a read-only composition step.

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 short sentences that front-load the action and the required reasoning, then disclose the return shape. Dense but every clause carries information; there is no filler or hedging.

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 an output schema and full parameter coverage, the description needn't explain return fields, and it correctly focuses on the two behavioral facts an agent could miss: the reason requirement for skipping the top option, and the dual output (journal line plus optional learning candidate). The only gap is no guidance tying it to the neighbouring outcome tools.

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 restates what the schema already documents (considered is best-ranked first; skipping the top option needs a rationale) rather than adding format, ordering or validation insight the agent could not read from 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 pairs a concrete verb with its resource ('Record what the owner chose') and enumerates exactly what gets captured: choice, options in rank order, and what was passed over plus why. It is specific enough to separate from record_outcome_experiment, but it never names that sibling or any other, so the differentiation is inferential rather than explicit.

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 one real conditional rule ('Passing over the top option needs a reason'), which tells the agent a precondition for a valid call. However, nothing states when to use this versus record_outcome_experiment or advance_outcome, and the critical gate 'only after the owner actually said so' lives only in the schema, not the description.

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 annotations, the description discloses validation rules that materially change how results must be interpreted ("Low volume forces INCONCLUSIVE; a broken guardrail is never a WIN") and enumerates outputs: an experiments.jsonl line, a learning candidate, and an anonymised report the owner may choose to share, implying no automatic disclosure. The one gap is that "Returns a line for experiments.jsonl" plus "Register/close" reads like state mutation while readOnlyHint=true, so the agent is left to infer that nothing is persisted server-side.

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, front-loaded with the two actions, then the invariant rules, then the returns—a sensible ordering with no filler. The parenthetical field enumerations partly duplicate schema content and add density, keeping it from a 5.

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 nested oneOf tool with an output schema, the description covers the decision-relevant essentials: both modes, the two outcome rules, and the shape of what comes back. The remaining ambiguity is whether the experiments.jsonl line is written or merely returned, which matters given readOnlyHint=true and would be worth one clarifying clause.

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 schema itself documents engagement, engagement_sha256 (hash-mismatch meaning) and the register/close oneOf branch. The description's field lists restate what the schema already requires per action rather than adding format, ordering, or precedence rules (e.g. what direction or target default to). Baseline 3 is appropriate when structured fields carry the semantics.

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 concrete verb and resource and splits the tool into two named modes ("action register" with change, metric, baseline, window, min volume, guardrails; "action close" with observed, volume, guardrail results, verdict), so an agent knows exactly what can be recorded. It does not name or distinguish the close-relative siblings such as read_back_outcome_experiment or record_outcome_decision, so a 4 rather than 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?

"Register a test before it goes live ... then close it" gives explicit lifecycle sequencing: register first, close when observations exist, with the action const in the schema binding each mode. There is no statement of when-not to use this tool or which sibling to choose for adjacent tasks (e.g. recording a decision), so it falls short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety and repeatability profile is fully covered without description help. The description adds the workflow context of a follow-up fetch and sketches the return record, which is useful but partly redundant given an output schema exists. It says nothing about result volume, ranking, rate limits, or what an empty result set looks like, so it adds only modest value above 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?

Two short sentences, front-loaded with the verb and resource, then the result shape, then the follow-up and the alternative — a sensible information order with no filler. The phrase "in the shape ChatGPT deep research and company knowledge use" is the one wordy stretch and leans on external context to convey meaning. Everything else 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?

For a one-parameter read-only search with full schema coverage, complete annotations, and an output schema, the description supplies what the structured fields cannot: the result record shape, the fetch follow-up, and the search_library contrast. Gaps around pagination and result limits are mitigated by the presence of an output schema. Only the absence of any result-count or ranking context keeps it from a 5.

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 one required parameter with 100% schema description coverage ("What to look for."), so the schema already carries the semantics and a baseline of 3 applies. The description never elaborates on the query — no guidance on phrasing, natural-language vs keyword, or the 300-character cap implied by the schema. Nothing is added beyond the schema for the single input.

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 pairs a specific verb with a specific resource ("Search AI Blocks") and characterizes the result shape (id, title, url), which lets an agent picture the output before calling. It also names the nearest sibling, search_library, and states the difference, so the tool is distinguishable from an otherwise near-identical alternative. The only drag is the vague framing phrase "the shape ChatGPT deep research and company knowledge use," which describes a style rather than a capability.

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

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

"Read one with fetch" gives an explicit next-step pointer to a named sibling, and the closing sentence contrasts this tool with search_library (filters and one-line summaries). What's missing is an explicit rule for when the plain search is preferable — the agent must infer that filter-free lookup means this tool rather than search_library. That inference is easy but not stated outright.

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 this a read-only, idempotent, closed-world operation, so the safety profile needs no restatement. The description still adds real behavioral context beyond them: result rows are 'compact', items must be explicitly loaded afterwards, their url should be cited, and the search is plain rather than model-backed. It stops short of describing ordering or pagination interaction between limit and offset.

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 most decision-relevant fact — search one item here, use start_outcome for a business goal — is front-loaded, and the rest is packed into tight parenthetical clauses. It is dense rather than padded, though the parenthetical style makes it slightly harder to scan than plain sentences.

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 10-parameter discovery tool with a full output schema and rich annotations, the description covers routing, browse-vs-query semantics, and the required follow-up workflow. What remains unstated (paging behavior, category's meaning) is either in the schema or not essential to calling 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 coverage is 60% on 10 parameters, so the description needs to help and it does: it groups type, job, level, tested and since as filters, and crucially explains the cross-parameter behavior that 'job or since' acts as a browse trigger when query is omitted. limit, offset, category and response_format are left to the schema, which is acceptable given the schema documents most of them.

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 scope ('Find one item for a task'), then enumerates exactly what is searchable (skills, workflows, agents, prompts, minds, AI tools, mini tools). It also draws a boundary against a sibling by name: 'for a whole business goal, use start_outcome', so an agent can distinguish this from outcome-oriented tools without opening any 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?

It clearly explains the two operating modes ('With no query, a job or since browses' vs keyword/intent search) and prescribes the follow-up path: load only chosen items with get_skill, get_workflow or get_item. The one gap is that other search-adjacent siblings such as search and find_specialist are never contrasted, leaving a sliver of routing ambiguity.

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 annotations, the description discloses what is returned (new engagement awaiting its brief, next step, files for outcomes/<id>/, METHOD.md with brief frame, research protocol, composition and run rules) and the cost/effect of include_example ('it is large', off by default). 'No work runs here' reinforces the read-only framing; a minor tension remains with 'Returns a new engagement' since scaffolding files is arguably a state change, but the disclosure is otherwise unusually rich.

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, front-loaded with the entry condition, then the return payload and the example option. Every clause carries operational information and nothing is repeated from the title alone.

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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them, which is helpful for a multi-artifact tool. The remaining gap is the unglossed started/engagement_id parameters and no note on whether repeated calls are safe, which matters given idempotentHint=true.

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 only 25%, so the description needs to carry weight; it does add meaning for include_example (what the worked example contains and that it is large) and implicitly defines request as the owner's own words. It says nothing about the started or engagement_id parameters (e.g., whether supplying engagement_id makes a re-run deterministic), leaving half the surface undocumented in both places.

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 gives a specific verb+resource: it opens a new engagement from an owner-stated goal and returns the scaffold, next step, and files under outcomes/<id>/. 'The front door for any goal or problem' plus 'No work runs here' implicitly separates it from advance_outcome and the prepare_* siblings, though none are named explicitly.

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

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

It clearly states the entry condition ('any goal or problem the owner states, in their own words') and rules out execution ('No work runs here'), which points the agent toward a later step. It does not name concrete alternatives such as advance_outcome or prepare_outcome_pattern, so the routing is implied rather than explicit.

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