Hyreflow

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

Annotations already cover read-only, non-destructive, open-world, so the bar is lower; the description still adds meaningful behavior: non-owner results are scoped to the caller (`scope: "member"`), and under a spend cap the balance reflects an allowance rather than total credits. It does not explain caching or freshness, but the key semantic caveats are disclosed.

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 what the tool returns. The scope/cap clause is compact but slightly cryptic, and 'their own' is vague about what is being scoped (spend vs. calls).

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

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

There is no output schema, so the description should convey the shape of the result. It names the main values (credits, recent spend, recent calls) and the member/allowance semantics, but leaves out the spend window, units, and how 'recent calls' are represented.

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 is 4. The description's mention of a `scope: "member"` result mode adds useful context even though it is not an 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?

States the specific resource returned: spendable credits and recent spend, scoped to this workspace. It has no explicit verb, but the resource and read intent are unambiguous and no sibling competes in the billing domain.

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?

Implied usage (check credits/spend) is clear, and the 'Free' note signals it costs no credits, but there is no explicit when-to-use or when-not guidance. The absence of any sibling billing tool makes this less harmful.

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, non-destructive and open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: reads the *live* version, includes the full version history in the result, and is explicitly 'Free' (no credit cost) – a behavioral/cost trait 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 core action and return shape, followed by the one parameter that needs semantic help, closed with a one-word cost note. Every sentence earns its place and nothing is padded.

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

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

There is no output schema, so the description must convey what comes back – it does, via the file-map shape and the version-history mention. It also covers cost. It stops short of explaining `skill_id` semantics or error behavior for an invalid version, but the essentials for correct invocation are present.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains `version` well (reads a non-live version, e.g. a draft awaiting owner approval), but `skill_id` is left entirely unexplained in both schema and description. Partial compensation only.

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 ('Return one custom skill's files') and even describes the return shape (`{path: text}`), which distinguishes it from the plain skill_read sibling by scoping to custom skills. It does not explicitly name the non-custom counterpart, so sibling differentiation is implied rather than stated.

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

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

The description gives clear guidance for the `version` parameter ('reads another version, such as a draft still waiting for the workspace owner'), which tells the agent when to use it. However, it never says when to choose this tool over `hyreflow_skill_read` or `hyreflow_custom_skills_list`, leaving the tool-selection decision 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?

Adds substantial behavior beyond the annotations (which only say readOnly=false, destructive=false, openWorld=true): prior versions are retained, personal versions go live immediately, team versions require workspace-owner approval unless the caller is the owner, and the operation is free. This is exactly the operational context an agent needs for a mutating 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?

Purpose is front-loaded in the first clause, followed by tightly packed but waste-free sentences covering file shape, mode selection, and release behavior. No filler.

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

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

No output schema is needed since the description explains the outcome (immediate live vs approval-gated, version retention). Combined with the annotations covering the safety profile, the definition gives an agent everything required to invoke 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 0%, so the description must carry the full burden, and it does: it defines `files` as the complete package of `{path: text}` with a SKILL.md frontmatter (name + one-line description) and text-only constraint, explains what `skill_id` triggers (versioning), and gives meaning to both `scope` enum values.

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 (create/save) and resource (custom skill) with clear dual-mode scope. An agent can distinguish it from hyreflow_custom_skill_read and hyreflow_custom_skills_list 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?

Explicitly tells the agent the two operating modes: omit skill_id to create, provide skill_id to save a new version. It also explains when to choose personal vs org scope. It does not, however, point to sibling tools (e.g. skill_read/list) for the alternatives, so routing guidance is slightly incomplete.

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, non-destructive, openWorld), so the description's added value is the cost note ('Free') and the enumeration of returned entry fields plus the scope enum values. This is useful context beyond structured data, though it omits anything about pagination or ordering.

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 scope-defining purpose before the field list and the trailing cost note. Dense but every clause carries information; 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 zero-argument list tool with no output schema, the description sensibly enumerates the returned fields and scope values and flags the cost, which is what an agent needs. Minor gaps are pagination/ordering behavior, which are not covered anywhere.

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 per the rubric the baseline is 4. The description's field listing (id, name, description, scope, live_version, pending_version) describes outputs rather than, but with no inputs there is nothing further to document.

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 ('List') and a precisely scoped resource ('skills this workspace's people wrote themselves'), then disambiguates the exact subsets returned (caller's personal skills and the team's skills). This distinguishes it from the sibling hyreflow_skills_list/hyreflow_skill_search, which cover non-custom skills.

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 scope wording ('people wrote themselves', personal vs org) implicitly tells the agent when this tool applies rather than hyreflow_skills_list, but there is no explicit when-to-use or when-not-to-use statement and no named alternative. Usage is inferable but not spelled out.

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=false and openWorldHint=true, but the description adds real context beyond them: the link opens in a signed-in browser session, and the response carries an `instruction` field for sign-in/not-found cases. This is useful behavioral disclosure the structured fields do not provide.

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, then browser behavior, then cost. Every sentence earns its place 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?

For a one-parameter tool with no output schema, the description covers the return shape (link plus `instruction` field) and the sign-in caveat well. Only the parameter's exact semantics remain thin.

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 0% schema description coverage, the description must carry parameter meaning. It does hint at the `dataset_id` format via the `ds_…` prefix, but does not otherwise explain the single required parameter. Partial compensation only.

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 ('Create a download link for a dataset's full CSV') and defines scope precisely ('every row and every column, not a sample'). This distinguishes it from the read/list siblings without needing to open their 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?

The 'not a sample' contrast implicitly routes the agent away from a preview-style sibling, but there is no explicit when-to-use statement or named alternative. Usage is implied 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?

Goes well beyond the readOnly/destructive annotations: discloses the default and hard page caps, the 500-row raise via columns, the ~60,000-character truncation with has_more/next_offset resume semantics, missing-path-as-null behavior, and cross-workspace 'dataset not found'. These are the operational traits an agent needs.

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: capability, caps, paging, format, columns, truncation, and auth scoping each appear in a purposeful sentence. No filler despite length.

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

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

With no output schema and no schema descriptions, the description fully covers return shape (row objects, CSV string, has_more/next_offset), multi-workspace behavior, and caps. An agent can call it correctly without other sources.

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 0%, so the description carries the full burden and does: limit (default 25, cap 100, raised to 500 with columns), offset paging, format enum with default and token implications, columns accepting keys/dotted paths with null fallback. Every parameter gains meaning beyond the bare 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 ('Read a page of rows from a stored dataset') and pins down the dataset id prefix (ds_…). Clearly distinguishable from siblings like hyreflow_dataset_export and hyreflow_datasets_list.

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?

Explains when to prefer csv (far fewer tokens) and that it's free, and clarifies paging via offset. However it doesn't explicitly contrast with a sibling such as hyreflow_dataset_export (e.g., use export for whole dataset, read for paging), so routing guidance is somewhat implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description adds ordering behavior (newest first), the exact fields returned per entry, and a cost hint ('Free') — all useful context beyond the structured data. It stops short of describing pagination behavior, which matters for a list 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?

Four tight sentences, front-loaded with purpose and ordering, followed by the context that makes the resource meaningful, then scope semantics. Nothing is padding; even the one-word 'Free' earns its place as a cost signal.

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 enumerates the returned fields (id, name, source, row_count, created_at), and annotations cover the read-only nature. The only real gap is undocumented limit/offset behavior for a paginated list.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It explains session_id well (narrows to one session; omitting it lists the whole workspace) but says nothing about limit or offset, leaving pagination semantics undocumented.

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 ('List this workspace's stored datasets (`ds_…`), newest first'), including the ID prefix convention that identifies the resource type. The explanation that datasets are the full-result store (vs. the 5-row sample in the original response) cleanly separates this from sibling tools like hyreflow_dataset_read and hyreflow_dataset_export.

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?

Explains when datasets exist ('any search or enrichment over 50 rows, and every workflow run's output') and clarifies the scoping choice between session_id and whole-workspace listing. It does not explicitly name alternatives such as dataset_read for fetching contents, so routing is implied 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 declare readOnly/safe, but the description adds substantial context beyond them: the credit cost (free), the credits-charged field, the full status lifecycle (pending | settled | failed | expired), and the meaning of a settled-but-empty result. This is exactly the added behavioral value the dimension rewards.

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 verb and resource, and each sentence carries operational value (polling guidance, no-email interpretation, cost). It is dense and somewhat long, but no sentence is filler.

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

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

With no output schema, the description itself documents the return shape (status, credits charged, email when settled, result) plus lifecycle and cost, so an agent knows both how to call it and what to expect. Nothing essential is missing for a two-parameter 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?

Schema coverage is 0% and both params are required, so the description must compensate. It explains job_id well as the `job` handle from a still_enriching row, but provider is left entirely unqualified with no accepted values or format, so half the parameter semantics remain undocumented.

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 (Fetch) plus resource (async enrichment job) and the identifying parameters (provider, job id). It further anchors the resource as 'the `job` handle on a `still_enriching` row', which distinguishes it from the job-creating sibling hyreflow_enrich_run without ambiguity.

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 strong operational context: a pending status means check again later, and a still_enriching row is not a miss. It stops short of explicitly naming the alternative tool or the exact polling cadence, but the when-to-use situation 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?

Far exceeds the annotations: it discloses the ~20s synchronous wait, the `_meta.status: "running"` + `run_id` fallback, the `still_enriching` row state and its `job_id`/`resume` handles, the free polling loop via `_meta.pending`/`poll_after_s`, 15-minute idempotent dedupe charged at 0, and the `expected_credits` vs `total_max_credits` cost split. These are exactly the traits (latency, cost, partial completion) an agent cannot infer from readOnly/destructive/openWorld hints alone.

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 core action and return shape, then layers on async/polling and cost semantics, with no filler sentences. It is dense prose rather than structured bullets, and the polling/`still_enriching` material sprawls across several sentences, making it harder to scan than necessary.

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 paid, asynchronous, no-output-schema tool this is unusually complete: return shape (summary not raw rows), `_meta` fields, row-level `still_enriching` handling, resume handles, polling cadence, and credit semantics are all covered. An agent could call it, interpret a partial result, and re-check correctly without further documentation.

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 75% schema coverage the baseline is 3, and the description earns more by explaining the behavioral difference between `rows` and `input` (a whole dataset becomes a NEW dataset with `_meta.dataset_id`) and clarifying that a call with only `run_id` is a free progress read. It leaves `dry_run`, `user_prompt`, and the step-shape semantics to the schema, which largely documents 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?

States a specific verb and resource ("Run ordered enrichment steps over a list of rows, each row independently") and adds a differentiating clause, "the CSV-style, per-column executor," which separates it from record-at-a-time executors. It never names the sibling it contrasts with (e.g. hyreflow_tools_execute, hyreflow_enrich_job, hyreflow_workflow_run), so the distinction stays implicit.

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 concrete selection rules between the two input modes ("Rows come from `rows`, or from a stored dataset via `input`") and between the run modes (`run_id` sent alone returns progress free). It also draws a scope boundary — "Enrichment adds data only; it does not screen or filter rows" — which implicitly routes filtering to hyreflow_shortlist, but it does not name an alternative explicitly.

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 say readOnlyHint=true and openWorldHint=true, which the description reinforces by being a fetch operation. It goes beyond annotations by disclosing: photos are shrunk and kept for 15 minutes, up to 500 rows or 100 URLs, returns apply_url with an instruction, skipped counts failures by reason, free. The 15-minute retention and rate/size limits are exactly the kind of extra context that matters.

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, starting with the core purpose and then the input choice. Multiple clauses are packed into long sentences, making it slightly heavy, but every clause adds distinct behavioral or parameter 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?

For a read-only, open-world fetch tool with no output schema, the description covers inputs, limits, retention, return shape, and failure handling reasonably well. However, it doesn't explain the apply_url workflow's relation to a write step or what happens if the page session expires after 15 minutes, leaving a small 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?

Schema coverage is 0%, so the description must carry parameter meaning, and it does: it clarifies what dataset_id triggers (engine reads every row's photo_url or profile.picture.source, up to 500) and what urls should contain (AI Ark and LinkedIn photo links, up to 100), plus the mutual exclusivity. This compensates well for the empty 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+resource: putting candidate profile photos into a hyreflow artifact page, with the key constraint that the page can't load images from other sites. This is distinct from siblings like dataset_read or enrich_run, though the description doesn't explicitly name which sibling produces the photo URLs.

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 a clear condition for use ('Call it only when the user wants photos') and explains the choice between the two parameters: dataset_id when rows came from a dataset, otherwise urls. It doesn't name alternative tools, but the mutual exclusion on inputs is spelled out well.

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 it is not read-only, is open-world, and is non-destructive; the description adds meaningful context beyond that: the issue is read by humans on the team, a URL is returned, and critically 'A submission cannot be withdrawn' plus 'Free' (cost). The irreversibility disclosure is exactly the kind of behavioral trait an agent needs before submitting on a user's behalf.

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

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

Four short sentences, front-loaded with the action, followed by outcome, durability, and cost. Every sentence carries information; 'Free.' is a terse fragment but communicates a real constraint.

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 appropriately notes that a URL is returned, and annotations cover the safety profile. The gap is the wholly undescribed 'repro_query' parameter, which an agent on a bug-report path would plausibly need to fill 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 0% and the description compensates only marginally: 'feedback or a bug report' loosely maps to the 'kind' enum, but 'repro_query' is never explained and 'message' semantics are left implicit. With three undocumented parameters, the description does not fill the gap left by 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 ('Send feedback or a bug report to the Hyreflow team') and clarifies the mechanism: it files a tracked issue and returns its URL. No sibling tool overlaps with this function, so an agent can route to it unambiguously.

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

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

Usage is implied by the description – an agent should call this when it or the user wants to submit feedback or a bug. However, there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives (there are none among siblings), leaving routing 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?

The annotations only say it is a non-read-only, non-destructive, open-world write; the description adds what actually happens — 50-file cap, empty files skipped, bodies over 64 KB truncated and marked, duplicate name+text skipped so resends are idempotent, existing notes untouched with numeric slug suffixes, and return of written versus skipped-with-reason. It also discloses multi-member visibility and that the call is free.

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 limits, then edge cases; almost every clause carries information an agent needs. It is a long comma-chained sentence, though, and would read better broken into two or three.

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 mutating bulk-import tool with no output schema and no annotation detail, the description covers dedupe/idempotency, truncation, slug collisions, partial-success return shape, and the approval precondition — nothing material is missing.

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

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

Schema description coverage is 0%, so the description carries the whole burden and does: each file has name and content, an optional kind with all six enum values enumerated, and up to 20 tags. It also supplies the 50-item array limit that the schema caps but does not explain.

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 — adding text files from the user's computer into the workspace's second brain as draft notes in the Imported folder. The bulk, per-file granularity and destination folder distinguish it from single-note siblings such as hyreflow_knowledge_write.

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 admissibility rule: send only files the user has seen listed and approved, with the rationale that every member's agent reads the notes. It implies bulk import rather than single-note editing but never names a sibling tool as the 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 read-only/safe semantics, so the description adds the non-obvious parts: entries omit page text, `build` reports the latest build state with its three enum values and null-when-unstarted, the result is empty when no brain exists, and the call is free. The empty/free/build-state disclosures are exactly the kind of context annotations cannot carry. It doesn't mention ordering, pagination, or size of the index, which is the only reason this isn't 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?

Front-loaded with the core action in the first clause, then field semantics, then edge cases. Dense but every sentence carries information. Slightly crowded by inline field lists and backticked names, which read like schema detail rather than routing guidance, but nothing is redundant.

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 takes on the burden of describing the return shape and does so: enumerated entry fields, the `build` status field with its value set, and the empty-when-unbuilt case. Missing only ordering/pagination and whether the whole index is returned at once, which matters for workspaces with many pages.

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 and 100% schema coverage, so there is nothing for the description to disambiguate. Baseline 4 applies; the description's discussion of returned fields (`build`, slug/title/type/folder/status/tags/updated_at) is return-shape information rather than parameter meaning.

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: lists every page of the workspace's second brain, with a parenthetical clarifying what 'second brain' means (notes about the business: roles, ideal customer, messaging). That is clear and concrete. It does not explicitly contrast itself with hyreflow_knowledge_read or hyreflow_knowledge_search, so the agent must infer the difference (metadata index vs. full page content / query) from the sibling names.

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

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

Usage is only implied: a plural 'List every page' plus the note that entries omit page text suggests this is a discovery step before hyreflow_knowledge_read or hyreflow_knowledge_search. There is no explicit 'use this when...' and no named alternative to route to, which for a workspace with three knowledge siblings is a real gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating exactly what the `full` view returns (data, sources, outbound and inbound links, unmatched link targets) and by flagging that calls are free.

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

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

Four short sentences, front-loaded with the core action and the parameter contract before the optional detail. The closing note about Persona Search filter pages is somewhat tangential but earns its place by telling the agent what kind of content to expect.

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

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

For a two-parameter read tool with annotations and no output schema, the description covers the action, both view payloads, the default, and the cost. An agent has everything needed to call it correctly and anticipate the shape of the result.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does so for `view`: both enum values are defined with their payload differences and the default is restated. `slug` is only named ('by `slug`') without format or lookup hints, which is the one remaining gap.

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 ('Read one page of this workspace's second brain by `slug`'), scoping it to a single addressable document. That makes it clearly distinct from the sibling list/search/index 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?

The two view modes are explained and a default is named, which tells the agent how to call it, but there is no guidance on when to reach for this versus hyreflow_knowledge_search or hyreflow_knowledge_index. The trailing 'Free' hints at a cost trade-off against paid siblings but never makes the routing 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?

Annotations already declare readOnly/openWorld/non-destructive, and the description adds genuinely new behavior: results are ranked, include a snippet, put drafts last, and exclude archived pages entirely. It also discloses the cost ('Free'), which matters alongside the billing sibling, but says nothing about result volume beyond the schema's limit or about rate limits.

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 in the first sentence, then query syntax, then result ordering/filtering, then the persona-filter use case. Very dense with no filler, though the trailing 'Free.' fragment and the run-on persona sentence make it slightly less scannable than it could 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?

Two parameters, no output schema, and the description covers the action, query grammar, return shape (ranked pages with snippet), ordering, exclusion of archived items, and billing. The only real gap is what a returned 'page' contains beyond a snippet and how to then read it, which the sibling read tool presumably handles.

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

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

Schema coverage is 50% — only `limit` is documented in the schema, so `q` relies on the description, which fully compensates by specifying query syntax (quoted phrases, `or`, -exclusions). `limit` is already covered by the schema's range and default, so the description does not need to repeat it.

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: search this workspace's second brain, returning ranked pages with snippets. It implicitly separates itself from hyreflow_knowledge_read/write/index by being the retrieval-by-query tool, but it never names those siblings explicitly, so the distinction is inferred rather than declared.

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

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

Gives clear operating context: web-search style query with quoted phrases, `or` and -exclusions, and points to Persona Search filter pages as the right target when building a people search with the provider tools. It stops short of stating when to prefer hyreflow_knowledge_read (fetching a known page) over searching.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real context beyond them: sources are preserved on update, taken slugs are refused, archived notes leave search, the change is immediately visible to every member's agent, and there is no undo. The 'write only what the user stated or confirmed' line plus the cost note ('Free') are exactly the operational details an agent needs before a destructive write.

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, then the upsert rules, then the safety constraints — a sensible ordering with no filler. Sentences are dense and pack multiple clauses (the slug rule alone carries three conditions), which costs a little readability but not substance.

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 six-parameter, no-output-schema mutation with no undo, the description covers mode selection, collision handling, status effects, blast radius (all members' agents) and cost. The only real omission is what the call returns (e.g. the resolved slug), which is minor given no output schema is declared.

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 17% (just `body` is documented), so the description must carry the load. It does explain `slug` (update key / collision refusal), `title` (required when no slug, source of derived slug) and `status: archived`. But `tags` and `folder` get no semantics at all, leaving half the surface undocumented.

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 states a specific verb pair (create/change) and an unambiguous resource (one note in this workspace's second brain), which distinguishes it from the read/search/index siblings. An agent knows immediately this is the write path, not a lookup path.

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 spells out the two operating modes precisely: existing slug means partial update with sources preserved, no slug means title is required, slug is derived, and collisions are refused rather than replaced. It also gives the `status: archived` condition for removing a note from search. It does not name sibling tools (e.g. search for an existing slug first), so it falls 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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: idempotency ('Repeat calls are harmless') and cost ('Free'), plus what the 'start' step returns. It stops short of describing what 'progress'/'completed' return or any auth/permission requirements, so not 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?

Four short sentences, front-loaded with the core action, then the step semantics, then the idempotency and cost facts. Every sentence carries distinct information with no redundancy.

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

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

With no output schema and only two simple parameters, the description supplies enough to drive the multi-step flow correctly, including what the first call yields. Minor gaps remain around what the later steps return and whether any prerequisites exist before starting.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does explain the semantics of both parameters: the three step values and their role in the flow, and that 'note' is a short message supplied while working. It omits the 120-character note limit, which the schema does enforce, so it falls short of complete compensation.

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 ('Run Hyreflow onboarding for the signed-in person') and clearly distinguishes itself from every sibling, none of which handle onboarding. An agent immediately knows this is a stateful onboarding flow rather than a data or skill tool.

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 maps each step to its use: 'start' is the default entry that returns instructions, 'progress' is called with a short note while working, and 'completed' is called at the end. The when-to-use sequence is fully specified with no inference required.

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/openWorld/destructive, so the bar is lower. The description adds meaningful context beyond them: that some matches are approximate ('rank dropped', 'root word') and that the call is free, both of which affect how an agent should treat and cost the results.

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, followed by match-quality caveat, downstream usage, and cost in three tight sentences with no redundancy. Every sentence carries distinct information.

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

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

For a read-only, 2-param lookup with no output schema, the description covers purpose, result shape, match reliability, and downstream usage well enough to call it correctly. The only real gap is the undocumented `limit` parameter.

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% for both parameters. `title` is self-evident from the purpose statement, but `limit` is never mentioned anywhere -- not in the schema, not in the description -- so its meaning and default must be guessed. The description does not compensate for the coverage gap.

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 (Resolve) and resource (job title → O*NET-SOC occupation codes), plus what each result contains (official title and description). This is unambiguous and distinguishable from enrichment/skill 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?

Explains a concrete use case -- feeding `onet_codes` into predictleads discover_job_openings -- and notes the call is free, which helps an agent decide to invoke it. It gives no explicit alternatives or when-not-to-use conditions, 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?

With annotations only declaring destructive/openWorld, the description carries real operational weight: it discloses credit charging, dry-run quoting, the 15-minute idempotency window returning the first run at zero cost, the ~20s wait and the run_id polling contract that is free, plus the fact that questions and full row profiles are persisted to a dataset. It also flags the refusal behavior for thin sourcing stubs.

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 capability and input choice are front-loaded, and nearly every sentence carries operative detail. The mid-section mixing polling, dataset storage, dedupe and charging is dense and slightly jumbled, but nothing is superfluous.

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 13-parameter, destructive, credit-charging tool with no output schema, the description does the heavy lifting: it explains both return shapes (ranked top-25 rows vs {run_id, status, progress, poll_after_s}) and the persisted dataset. Gaps remain around `min_score`, `allow_thin_profiles`, and `regenerate_questions` semantics.

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 69%, and the description adds genuine meaning for the main parameters: `job_spec`, `candidates` (row objects from a CRM/ATS search, needing work history), `input` (ds_ dataset id), `run_id`, `dry_run`, and the generated-and-reused `questions`. It leaves `min_score`, `allow_thin_profiles`, and `regenerate_questions` unaddressed, which the schema does only partially.

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 opens with a specific verb and resource ('Bulk-screen candidates against a job description') and immediately states the output shape: one structured decision per candidate, ranked, with tier and per-category scores. No sibling in the list does candidate screening, so an agent can identify this tool without reading 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?

It clearly distinguishes the two input paths (inline `candidates` up to 1000 rows vs a `ds_` dataset id via `input` for a larger pool), and explains the polling path via `run_id`. It does not address when to prefer a sibling like `hyreflow_enrich_job` or `hyreflow_dataset_read` instead, so routing between tools remains 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 readOnly, non-destructive, open-world. The description adds meaningful context beyond them: that the full document is returned untruncated and that the call is free (no billing), which matters given the hyreflow_billing_balance sibling. It does not describe size limits or output 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?

Two sentences, front-loaded with the core action, then parameter mechanics, then the cost note. 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 2-parameter read tool with no output schema, the description covers the action, both parameters with examples, and the no-cost property. Only the error/not-found behavior and return format boundaries are unstated, which is minor.

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 0%, so the description must carry the load and largely does: 'skill' is a package name with an example, 'path' selects a document inside it with an example, and a hyreflow://skills/ URI is accepted whole. Edge cases like path traversal or invalid names are not addressed.

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 ("Return one skill document in full") and clarifies scope versus list/search siblings implicitly by emphasizing a single document. It does not explicitly differentiate from hyreflow_custom_skill_read, which is the closest sibling.

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: use this when you need the content of a known skill or path. The 'skill' vs 'skill + path' selection logic is spelled out, but there is no explicit when-not guidance or named alternative (e.g., use hyreflow_skill_search to discover, this to read).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds beyond that: full-corpus scope ('every ... document'), the shape of the result ('matching lines'), and a cost disclosure ('Free') that matters given the hyreflow_billing_balance sibling. Missing details like ranking or pagination behavior keep 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?

Two tight sentences with the verb and scope front-loaded, followed by the return contract and cost note. No filler; every 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?

There is no output schema, so the description correctly supplies the return shape (matching documents plus matching lines). It is nearly complete for a simple 2-parameter search tool, with the only gap being the undocumented limit parameter.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain what q should contain (a provider name, a field, a capability), which is genuinely useful, but the limit parameter is left entirely unexplained in both schema and description.

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 (every Hyreflow skill document) with the searchable term types and the return shape ('documents that mention it, with their matching lines'). This functionally separates it from hyreflow_skills_list (enumerate) and hyreflow_skill_read (fetch one), so an agent can route correctly 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?

The parenthetical examples ('a provider name, a field, a capability') imply when the tool is appropriate, and 'Free' hints at cost trade-offs versus the billing sibling. But no explicit when-to-use, when-not-to-use, or named alternative (e.g., skill_read for a known doc) is given.

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=true, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds that it is free and characterizes the documents, but says nothing about pagination, size, or format of the list. Adequate but not rich beyond the annotations.

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 compact sentence front-loads the action and then enumerates the content, with 'Free' tacked on. Efficient, though the parenthetical is dense.

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

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

For a zero-parameter, read-only listing tool with annotations covering safety and openness, the description tells the agent what will be returned. Adequate; only return format details are absent, which is minor for a simple list.

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 explain; baseline 4 applies. The enumeration of document categories is content context rather than parameter guidance.

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 (List) and resource (Hyreflow skill documents) and enumerates the content categories, which distinguishes it from siblings like hyreflow_skill_read and hyreflow_skill_search.

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?

Implies a discovery/enumeration use case and notes it is free, but does not say when to prefer this over hyreflow_skill_search or hyreflow_skill_read. No exclusions or conditions given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully adds that the call is free (no credit cost) and what the response contains, including the machine-consumable payload and the covering skill doc. It does not discuss auth or rate limits, but for a read-only descriptor that is a minor omission.

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 a colon-delimited list of return contents. No filler, no redundancy, and the core action precedes the payload enumeration.

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

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

For a two-parameter, read-only descriptor with no output schema, the description covers what is returned and the cost. The notable gap is not telling the agent where valid tool/method identifiers originate, which matters given a sibling tools_search exists.

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

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

Schema description coverage is 0% for both parameters, so the description must carry the load. It partially does: 'one Hyreflow tool and its methods' implies the required `tool` selects the tool and the optional `method` narrows to a single method. It gives no format or sourcing hints (e.g., that tool/method names come from tools_search), so the coverage gap is only partly closed.

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 (describe) and resource (a Hyreflow tool / one method), and enumerates the payload returned: expected payload, credit cost, usage notes, and covering skill document. It is clearly distinguishable from tools_execute or tools_search by intent, though it never names those siblings 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?

The 'tool and its methods, or one method in full' phrasing implies when to use the whole-tool form vs the method form, and 'Free' hints at cost considerations. However, it never states when to reach for this over hyreflow_tools_search or hyreflow_skill_read, leaving the routing to inference.

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

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

Goes far beyond the annotations: credits are charged at the described cost, dry_run quotes without running, pending rows poll free, identical `rows` within ~15 minutes replay a stored dataset at no charge, and a resend after a run is refused. This is exactly the mutation/cost/side-effect detail an agent needs and 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?

Nearly every sentence carries information, but it is one undifferentiated block and repeats the replay rule twice (the 15-minute dataset replay is restated at the end as 'an identical multi-row `rows` batch... replays its stored dataset at no charge'). The critical facts – cost, dry_run, confirmation – are front-loaded, which helps.

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, and the description compensates well by naming the response shapes: `still_enriching`, `job_id`, `resume`, `_meta.pending`, `_meta.instruction`, `_meta.poll_after_s`, `_meta.dataset_id`, `_meta.replayed`, `confirmation_required`. The main gap is that it never says how to obtain valid `tool`/`method` values, leaving discovery implicit.

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 only 44% schema description coverage across 9 params, the description carries real weight: it explains that `rows` accepts up to 100 objects (mirroring maxItems) and substitutes for `payload` and `method`, and it explains `confirm_token`/`approved_credits` in context of the confirmation flow. `channel` and `user_prompt` are left to the schema, and `tool`/`method` semantics (how to discover valid values) are only implied.

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: 'Execute a Hyreflow tool method against live data providers', and immediately frames the charging model. It implicitly distinguishes itself from hyreflow_tools_search/describe (discovery vs execution) but never names those siblings, so an agent must infer the routing.

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 concrete operational conditions: `dry_run: true` for a quote, `rows` for enrichment waterfalls instead of `payload`/`method`, waterfall tools take only `payload`, and the confirmation-threshold path is spelled out. Missing explicit guidance on when to prefer this over hyreflow_enrich_run or hyreflow_workflow_run, so not 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 the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely new context: the operation is free, and results include credit cost and a side-effect flag, which helps the agent reason about downstream calls.

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

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

Three tight sentences, front-loaded with the core purpose, then return shape, then the language constraint. Each sentence carries information; only the English constraint is slightly repeated between description and schema.

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

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

With no output schema, the description correctly explains what comes back (matching tool names with credit cost and side-effect flags). For a two-parameter read-only search tool this is nearly complete; only the limit parameter's 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 coverage is 50%: q is documented in the schema, but limit is undocumented in both schema and description. The description reinforces the English-intent constraint on q (already in the schema) and adds the cross-language nuance, but does not compensate for the unexplained limit parameter.

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

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

States a specific verb and resource ('Search the Hyreflow tool catalog by intent') and gives a concrete example query, so the agent knows exactly what this does. It does not explicitly differentiate itself from siblings like hyreflow_tools_describe or hyreflow_tools_execute, which would be needed for 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?

Provides a real usage constraint ('describe the intent in English whatever language the user wrote in') and cost information ('Free'), which imply this is the entry point of a search→describe→execute flow. However, it never states when to use this versus hyreflow_tools_describe or hyreflow_tools_execute, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the description is not obliged to re-state the safety profile. It adds genuinely new behavior: a live run charges credits for the tools it calls, and it returns the run id plus initial status. It does not explain what dry_run or smoke_test actually do.

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, no filler, with the core action front-loaded and the cost caveat placed last where it matters most.

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?

The description covers the queued-run model, the accepted workflow identifiers, and the return shape, and there is no output schema to explain. However, for a destructive, credit-charging, open-world mutation with an unexplained mode enum, the omission of dry_run/smoke_test semantics and of what 'input' does leaves a real gap before an agent can 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 coverage is only 25%, so the description must carry the load, and it mostly does not. It clarifies that 'workflow' accepts a name or id, but the mode enum (live vs dry_run vs smoke_test) — the single most consequential parameter choice — and the nested 'input' object are left entirely unexplained; the credit note only obliquely implies what live means.

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 ('Queue a run of a saved workflow in this workspace, by name or id'), which is clearly distinct from the sibling hyreflow_workflow_runs list tool. It stops short of naming that sibling explicitly, so it is clear but not fully self-differentiating.

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 reader can infer this is the tool for kicking off an existing workflow rather than listing or defining one, and the credit caveat hints at cost trade-offs. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., preferring dry_run first, or using hyreflow_workflow_runs to poll).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description does add one behavioral fact not in structured data — the call is free — and hints at return content ('status and timing'), but says nothing about pagination, limits, or how 'recent' is bounded.

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 with the resource and scope front-loaded and no filler. The terse 'Free' fragment is unconventional but does convey cost information efficiently.

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

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

For a simple read-only list tool whose annotations carry the safety profile, the description covers purpose but leaves the required 'workflow' identifier format and limit semantics unspecified, and no output schema exists to fill the return-shape 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?

Schema description coverage is 0%, so the description must carry the parameter burden and does not: it never explains whether 'workflow' is a name, ID, or slug, nor what 'limit' defaults to or caps at. Only the loosely implied association between the workflow and its runs is conveyed.

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 ('List recent runs of a workflow') and adds scope detail ('status and timing'). It is clearly distinct from the singular sibling hyreflow_workflow_run and from hyreflow_workflows_list, though it never names those siblings 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 hyreflow_workflow_run or hyreflow_workflows_list, and no prerequisites or exclusions are stated. The only usage signal is the implied cost note 'Free', which is about pricing, not selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the cost signal ('Free'), which is genuinely extra information not present in structured fields, but says nothing about result size, ordering, or pagination.

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 with the resource front-loaded and zero filler. Every clause earns its place, including the cost note.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers what is being listed and that it is free. It could be slightly more complete by noting ordering or result scope, but nothing critical 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. Nothing in the description is needed to compensate for schema gaps.

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 ('List') and resource ('cloud workflows saved in this Hyreflow workspace'), so the agent knows exactly what it retrieves. It does not explicitly contrast itself with siblings like hyreflow_workflow_run or hyreflow_workflow_runs, but the 'saved workflows' scope is clear enough to distinguish it.

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 the sibling run-related tools, and no stated prerequisites or exclusions. The only contextual signal is 'Free', which hints at cost but not usage conditions.

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