Heliyos MCP server

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

Annotations only say destructive, non-idempotent, non-read-only; the description goes well beyond by disclosing the approval gate for consequential actions, the 90 s wait ceiling, the minimum 120 s client timeout requirement, credit consumption, and the dual-run consequence of repeated calls. These are the operational facts an agent cannot infer from the annotations and would otherwise trip over.

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 examples, then moves efficiently through safety, timing, follow-up, and cost. Minor waste: it restates the return payload both inline ({run_id, status, thread_id}) and again at the end as structuredContent, which is redundant given an output schema exists.

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 complex, long-running, destructive orchestration tool this covers everything an agent needs before calling: scope of side effects, approval semantics, latency and timeout, follow-up path, conversation continuity, and cost model. Return values are additionally spelled out even though an output schema is 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 coverage is 100% and both parameters are already documented in the schema, so the baseline is 3. The description's note about passing thread_id to continue the same conversation largely restates the schema field description and adds nothing about the 20,000-character message limit or content expectations.

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 ('Asks Heliyos (the orchestrator and its workers) a question or gives it a job, in plain language') and backs it with two concrete examples that show the level of abstraction expected. It is clearly distinguishable from the granular siblings like heliyos_records_update or heliyos_tasks_create because it is the natural-language entry point.

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 routes the agent: use this for plain-language jobs, call heliyos_runs_get with wait: true when the result is 'Still running', and pass thread_id to continue a conversation. It also gives a pre-call instruction ('confirm jobs that change things with the user first') and warns that calling twice starts two runs, which is exactly the when/when-not guidance an agent needs.

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 the mutation profile (readOnly=false, destructive=false, openWorld=false), and the description adds real context beyond them: setup runs asynchronously and must be polled via heliyos_companies_scouts_list, scout runs consume credits, and duplicate scouts are skipped. The credit cost is the most valuable disclosure since idempotentHint=false means repeat calls can carry cost. The skip-if-running rule is not a contradiction of idempotentHint but a clarification of it.

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

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

Four sentences, each carrying a distinct fact (precondition, async behavior, dedupe, cost), with the core action front-loaded. The final sentence restating structuredContent fields duplicates the existing output schema and could be dropped without loss.

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 mutation that fires async work and spends credits, the description covers the required input constraints, the polling path, dedupe semantics, cost, and return shape — and an output schema exists so return details need only a pointer. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a validity constraint the schema cannot express: scout_ids must reference active global scouts with apply_to watchlist. It does not elaborate on the 50-item cap or id format, which the schema already handles.

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 opening sentence gives a specific verb and resource — 'Starts the given scouts on one company' — which separates it from heliyos_scouts_create (defines a scout) and heliyos_companies_scouts_remove (detaches). Sibling differentiation is implicit in the wording rather than stated by contrast, so it stops just short of a 5.

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

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

It states the precondition that each scout_id must be an active global scout with apply_to watchlist, and routes the agent to heliyos_scouts_list to find valid ids and to heliyos_companies_scouts_list to verify the result. It also notes an already-running scout is skipped, effectively a when-not condition. No explicit statement of when removal or a different sibling is preferable.

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 behavior the annotations cannot: no paging because the collection is small, the status enumeration, and a sketch of the returned structuredContent. It does not state ordering or behavior for an unknown company_id.

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 dense sentences, front-loaded with purpose and followed by the return shape; nothing is wasted. The second sentence is somewhat packed with field lists and an inline tool reference, but it remains readable.

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 only two parameters, full schema coverage, an output schema, and rich annotations, this is nearly complete: it covers what is listed, that paging is unnecessary, and the shape of the response. Minor omissions such as whether the status filter is optional or how results are ordered keep it just short of full marks.

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

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

Schema coverage is 100%, so both parameters are already documented, including the enum values and the company_id pattern. The description largely restates the status values and the company_id linkage rather than adding new syntax or semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists the scouts running on one company') and immediately scopes it to a single company, which distinguishes it from the global heliyos_scouts_list and from heliyos_scouts_get. The enumerated fields (id, scout_id, status, cadence, last run) make the payload predictable.

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 usage context: 'A company has only a few, so there is no paging,' which tells an agent not to expect pagination, and it routes the agent to heliyos_scouts_get via the global scout_id. It stops short of an explicit when-not-to-use statement (e.g., versus heliyos_scouts_list), so it is clear rather than exhaustive.

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 destructive and idempotent, but the description adds the consequences an agent cannot infer: existing signals are retained, the company remains watched, the action is irreversible, and the return payload can report partial failures. This is exactly the extra behavioral context the annotations do not carry.

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

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

Three tight sentences ordered by importance: scope, side effects, irreversibility. Nothing is repeated from the schema or annotations, and no sentence could be dropped without losing 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 single-parameter destructive tool with full annotation coverage and an output schema, this covers everything an agent needs: scope, retained state, irreversibility, and failure reporting. No gaps remain.

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 company_id field is already documented with format and a lookup pointer, so the description correctly omits parameter detail. It adds no meaning beyond the schema, which is the expected baseline here.

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 (stops and removes) and resource (every scout on one company), with an explicit scope boundary — no per-scout removal — that separates it from heliyos_scouts_delete and heliyos_companies_scouts_add.

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?

Clearly frames both when to use it (bulk removal for a company) and how the scope differs from per-scout operations, plus a confirmation requirement before invoking. It does not name the alternative tool for single-scout removal, which keeps it from 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 flag destructiveHint=true and idempotentHint=true, but the description adds the crucial detail of what exactly is destroyed (Scouts) versus preserved (emails, meetings, notes, signals). It also carries a human-confirmation requirement that appears nowhere in the structured fields.

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

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

Three tight sentences ordered by importance: what it does, what happens to data, then the confirmation gate. The trailing 'Returns structuredContent {record_id, watched}' is mildly redundant given an output schema exists, but it is brief and harmless.

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 single-parameter mutation with an output schema and full annotations, the description covers everything an agent needs: destruction scope, preservation semantics, reversibility, and the confirmation requirement. Nothing material is left to inference.

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 record_id parameter is already documented in the schema with its source (heliyos_records_list or _lookup). The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Removes a company record from the watchlist'), which is clearly distinct from heliyos_companies_watch, heliyos_watchlist_get, and heliyos_records_delete. An agent can tell from the first clause exactly which operation this performs.

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

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

Gives an explicit precondition ('Confirm with the user first') and clarifies the reversibility model ('watching it again resumes where it left off'), which tells the agent this is not terminal. It stops short of naming the counterpart tool (heliyos_companies_watch) or stating when to prefer heliyos_records_delete 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?

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses the real side effects — enrichment workers, email/meeting pulls, Scout startup — plus two cost dimensions (watched-company plan limit, credit consumption) and confirms idempotency in plain language. That is exactly the behavior-over-annotations value this 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?

Three sentences, front-loaded with the action, then cost, then idempotency, then return shape. No sentence is padding; each carries a distinct fact an agent needs before calling.

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 mutation with an output schema, everything an agent needs is present: side effects, billing/limit impact, no-op semantics, and the structuredContent keys. Nothing material is left to inference about what calling it commits you to.

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 single record_id parameter already documents its 24-hex format and its provenance (records_list or _lookup). The description adds no additional meaning about the identifier, 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?

The description opens with a precise verb+resource pair ('Adds a company record to the watchlist') and immediately enumerates the concrete consequences — enrichment, email/meeting ingestion, Scout activation — so an agent can distinguish this from heliyos_companies_unwatch or a plain record update without opening either schema.

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

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

It gives clear decision context: the action consumes a plan-limited slot (cross-referencing heliyos_organization_get) and burns credits, and is a no-op for already-watched companies. What it lacks is explicit routing advice — nothing says to check heliyos_watchlist_get or heliyos_records_get first to avoid spending credits unnecessarily.

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 it discloses the non-obvious operational constraints: the key is derived from the label unless supplied, must be unique on the object, and repeat calls with the same key fail; AI columns consume credits and only certain types support ai_prompt. It even names the return shape, structuredContent {field:{field_id, key, label, type}}, so the agent knows what comes back.

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 and required inputs are front-loaded, and each subsequent clause adds a distinct constraint rather than repeating the schema. It is a dense single block, though, and could be split into a short usage sentence plus a constraints list for easier scanning.

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

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

For an 11-parameter mutation tool with an output schema, the description covers the decision points an agent needs: which object types, when schema_id is needed, when options is needed, how the key is derived and what happens on collision, and what the response contains. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description earns more by documenting cross-parameter conditionals the schema does not: options is required for select/multiSelect, schema_id is required when object_type is "custom", and key derivation rules tie key to label. Secondary parameters such as hidden, required, visibility and description are left entirely 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?

"Adds one field (column) to an object" gives a specific verb and resource, and then enumerates the valid targets (companies, people, deals, custom objects) and the required shape (object_type + schema_id for custom). It also scopes the operation by excluding relationship fields, so an agent can distinguish this from field-editing and record-level tools at a glance.

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 states when the tool applies and several when-not cases: relationship fields must be created in the Heliyos web app, and backfilling existing records with an AI prompt is started from the web app, not here. It does not explicitly route to heliyos_fields_update for modifying an existing field, which is the one obvious disambiguation left 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 declare destructiveHint=true and idempotentHint=true, but the description adds the material consequences an agent actually needs: deletion is permanent and irreversible, it wipes the value on every record, built-in fields are rejected by the platform, and the response shape is structuredContent {field_id, key, deleted}. This is meaningful behavior beyond the annotation flags.

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 compact sentences, front-loaded with the destructive scope before the confirmation requirement and the platform restriction. Every clause carries operational information; nothing is redundant 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 destructive three-parameter tool this covers the essentials: what is destroyed, irreversibility, the required user confirmation, the platform-level restriction, and the return shape. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantic value by telling the agent where field_id must come from (heliyos_objects_get) rather than letting it guess. It does not add anything on schema_id or object_type beyond what the schema's enum and conditional note already provide.

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 ("Permanently deletes one field of an object by field_id") and immediately clarifies the blast radius: the field AND its value on every record. That scope statement distinguishes it cleanly from the sibling heliyos_fields_update without requiring the schema to be opened.

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 concrete precondition (field_id comes from heliyos_objects_get) and a when-not rule (built-in required fields such as a company's name are refused by the platform). It also prescribes a confirmation protocol naming the field and object. It stops short of naming an alternative sibling such as heliyos_fields_update for non-destructive edits, so it is clear context rather than 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description explains exactly why the operation is destructive: options REPLACES allowed values and records holding a removed value keep it as stale text. It also discloses the platform-side refusal on incompatible type changes, that the field key is immutable, and that the response is structuredContent {field}, all of which the annotations do not convey.

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

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

Three front-loaded sentences plus a return-value clause, with the highest-risk fact (options replaces values, leaving stale text) surfaced early. No redundant restatement of the name or title.

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 destructive mutation with an output schema, the description covers partial-update semantics, the destructive edge case, the type-change refusal, immutability of the key, and the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema lacks, notably that options overwrites rather than merges and that a type change is rejected when existing values do not fit. It does not otherwise elaborate on individual parameters such as ai_prompt's credit cost or schema_id's requirement, which the schema already handles.

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 ("Changes one field of an object by field_id") and immediately tells the agent where field_id comes from (heliyos_objects_get), which separates it from heliyos_fields_create and heliyos_fields_delete without opening another 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 states the partial-update contract ("What you leave out is kept") and the preconditions for a type change, which tells the agent how to call it safely. It does not explicitly name the alternative tools (fields_create/fields_delete) or the when-not condition, so it falls short of a full routing statement.

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 already declare destructiveHint=true and idempotentHint=true, so "cannot be undone" mostly restates structured data. The genuine added context is the downstream effect: a knowledge-base file "disappears from what the workers can read," which the annotations cannot express. It also notes the structuredContent return shape, though an output schema already 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 short sentences, front-loaded with what gets destroyed, then the irreversible consequence and the confirmation requirement. Every clause carries information; nothing is padding.

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 single-parameter destructive tool, the description covers the action, the irreversibility, the required user confirmation, and the side effect on worker visibility. Since an output schema exists, the brief return-value mention is a bonus rather than a gap.

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

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

There is a single parameter with 100% schema description coverage, and the schema already documents the 24-hex-char id pattern and points at heliyos_files_list as the source. The description only restates "by id" and "one file," adding no new meaning, 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 with scope: "Permanently deletes one file by id." That cleanly separates it from heliyos_files_list, heliyos_files_get, and heliyos_files_upload without needing to open 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?

Gives an explicit precondition — "confirm with the user first" — that tells the agent when this call is appropriate and what gate must pass before invoking it. It does not name alternative tools (e.g., heliyos_knowledge_entries_delete) for the adjacent case of removing knowledge content, which keeps it 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 declare read-only, idempotent, non-destructive, non-open-world behavior, and the description correctly does not restate that. It does add genuinely new behavior: the signed download link's ~60 s expiry and the warning to consume it immediately, which no annotation conveys. Not describing not-found/error behavior or whether links can be re-fetched keeps it short of 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?

Three short sentences, front-loaded with the core capability, then the conditional 'detailed' behavior and its time constraint, then the return shape. No filler and the most actionable warning (use the link at once) is not buried.

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

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

For a simple two-parameter read with a full schema and an output schema, the description covers purpose, the format branch, the expiry hazard, and the structuredContent wrapper. Only error/not-found handling is unaddressed, which is minor at this complexity.

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 enum descriptions already explain concise vs. detailed including the 60 s validity, so the description's mention of 'detailed' is largely duplicative of structured data. The id format and required-ness are handled entirely by the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetches one file's details by id') and enumerates exactly what comes back: name, kind, type, size, description, and attached records. The 'by id' framing plus the single-object scope distinguishes it cleanly from the sibling heliyos_files_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?

Gives a real operational constraint for one path — the detailed download link expires in about 60 s, 'so use it at once' — but never says when to prefer this tool over heliyos_files_list, heliyos_files_delete, or heliyos_records_get for attached records. The only id-sourcing hint lives in the schema ('File id from heliyos_files_list'), 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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-structured behavior: newest-first ordering, the exact fields returned per file, the next_cursor pagination contract, and a handoff to the download 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?

Three tight sentences, front-loaded with the primary behavior and ending on the sibling handoff. Restating structuredContent {files:[...], next_cursor} is mildly redundant given an output schema exists, but it is compact and useful as a quick shape preview.

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 list tool with an output schema and full annotations, the description covers purpose, the two file kinds, all main filters, ordering, pagination, and the follow-up tool. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining what the kind values mean in practice and by tying record_id to 'the record a file is attached to'. It does not mention response_format at all, leaving that parameter 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?

States a specific verb and resource ('Lists files') plus scope: knowledge-base files vs attachments on records, with an explicit ordering (newest first). The two kinds are defined in domain terms ('documents the workers read'), which an agent cannot infer from the enum alone.

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

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

Explicitly routes the agent to heliyos_files_get when a download link is needed, and explains the available narrowing options (kind, record_id, name). It stops short of stating when-not-to-use it, e.g. that browsing records themselves belongs to heliyos_records_list.

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 non-idempotent and non-destructive, but the description adds substance the annotations cannot: a 10 MB size cap, a refusal list (HTML, SVG, XML, scripts, executables), content-type guessing from the extension, and the concrete consequence "Calling it twice stores two files." It also discloses the return envelope, so an agent knows what comes back.

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 verb and resource, then the size limit, then the kind split, then encoding rules and refusals — a sensible order. It is a dense single block with heavy parentheticals, and the trailing return-value sentence is largely redundant given the output schema, but almost nothing else is wasted.

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

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

For a six-parameter mutation upload with an output schema, the description covers everything an agent needs to call it correctly: size limit, kind semantics, encoding choice, content-type default, rejected types, attachment target, and duplicate-write behavior. Nothing material is left to inference.

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 a baseline of 3 is warranted, but the description adds meaning the schema lacks: the mutual-exclusivity constraint between text and content_base64 (the schema has no oneOf/anyOf to enforce it) and the default-resolution behavior of content_type when omitted. record_id's single-record limitation is also restated in plainer terms than the schema's regex-scoped field.

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 and resource ("Uploads one file") and immediately distinguishes the two file kinds it can create, which no sibling does — files_get/list/delete are read or removal operations. The 10 MB ceiling and the two storage modes make the tool's identity unambiguous.

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 conditions: use knowledge_base for documents workers read (playbooks, pricing) versus attachment, and use text for UTF-8 versus content_base64 for binary, "exactly one of the two." That is real when-to-use guidance. It stops short of naming alternatives or stating when not to upload at all (e.g., updating existing knowledge via the knowledge tools).

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 value beyond that by naming the returned fields and explaining the response_format trade-off ("concise" cuts the summary, "detailed" returns all of it). It does not state what happens for a missing or malformed id, which is the main remaining behavioral gap.

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 compact sentences, front-loaded with the verb+resource and then the return contents, with zero padding or restated title. The response_format clause slightly duplicates the schema, but it is short enough to earn its place as a scannable summary.

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 full schema coverage, complete annotations, and an output schema, everything an agent needs to call it correctly is present: the id source, the format switch, and the return payload shape ("structuredContent {interaction}"). No material gap remains.

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 includes an enum with a default, so most parameter meaning is already structured. The description still adds the provenance of interaction_id (list or timeline) and frames response_format as a summary-length dial, which is useful framing even though the schema spells out the 300-character cutoff in more detail.

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?

"Fetches one synced email thread or meeting by id" gives a specific verb, a specific resource (a single interaction, not a list), and the retrieval key. The remaining clauses enumerate exactly what comes back (subject/title, time, AI summary, sentiment, linked records, participants, next steps), so it is clearly distinguishable from heliyos_interactions_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?

The description tells the agent where the required id comes from ("from heliyos_interactions_list or heliyos_records_timeline"), which is real routing guidance for a get-by-id tool. It stops short of explicit when-not conditions or stating that heliyos_interactions_list should be used for browsing rather than this tool, so it is clear context without exclusions.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavior: newest-first default, what each item carries, that detailed expands participants and next steps, and the returned structuredContent shape including next_cursor. Pagination contract is spelled out well; no rate limits or auth notes, hence a 4.

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 what is listed and the default order, then filters, then the response shape, then the sibling alternative. Every clause carries information; no filler or repetition.

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 filter-and-paginate list tool with a nested sort object, the description covers scope, ordering, filtering, page size behavior via cursor, response verbosity, and the return envelope. With an output schema present, return values need not be fully re-explained, so nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the key filters (record_id, channel, sort, detailed) but adds little beyond what the schema already documents, including the concise/detailed cut at 300 characters.

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 (lists) and resource (synced emails and meetings) plus default ordering, and distinguishes itself from heliyos_interactions_get by naming that sibling as the single-item variant. An agent can tell which of the two to call without opening either schema.

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

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

Gives clear selection conditions: use record_id to scope to one record, channel to scope to emails or meetings, and switch to heliyos_interactions_get when a single interaction with its full summary is wanted. It lacks explicit when-not guidance (e.g. preferring search or timeline tools for other lookups), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is structured data; the description still earns credit by spelling out the consequence in prose ("This cannot be undone") and by stating exactly what survives the call ("The fixed texts and other entries are kept"). That blast-radius statement is information the annotations do not carry.

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

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

Three short sentences, front-loaded with the action and its scope, then the irreversibility warning, then the return contract. No filler and nothing 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?

For a single-parameter destructive tool with full annotations and an output schema, the description covers action, blast radius, confirmation requirement, and a summary of the return payload — enough to call it safely. The only gap is the not-found / no-op outcome, which matters given idempotentHint=true but is left unstated.

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

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

Schema description coverage is 100% and the schema already documents the label's length bounds and case-insensitive matching, so the baseline applies. The description's phrase "by label" restates the parameter rather than adding format, aliasing, or failure semantics beyond what the schema provides.

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?

"Removes one custom knowledge entry by label" gives a specific verb (removes), a bounded scope (one), and the resource qualified as "custom", which implicitly separates it from the fixed texts handled elsewhere. It stops short of naming a sibling such as heliyos_knowledge_entries_set, so the agent must infer the boundary from the shared vocabulary rather than being told.

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 supplies a hard precondition ("confirm with the user first") which is genuine operational guidance, and the word "one" plus "by label" implies single-entry deletion. However it never states when to prefer this over heliyos_knowledge_entries_set or heliyos_knowledge_update, nor what happens if the label does not exist, so the when-not guidance is missing.

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 non-read-only, idempotent, non-destructive, so the safety bar is largely met; the description still adds real value by clarifying that the operation is an upsert keyed on label and that other entries and fixed texts survive. It also discloses the response shape (entry, created, entries), the created flag being useful for distinguishing insert from update.

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 operation and its upsert scope, then usage example, sibling pointer, and return shape. Only the return-shape sentence is arguably redundant given an output schema exists, but it is terse enough not to be waste.

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, full parameter coverage, and clean annotations, the description covers what remains: upsert identity, preservation of other data, and the alternative for removal. The only gap is not naming heliyos_knowledge_update explicitly when contrasting with "fixed texts", leaving a small inference for the agent.

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 parameters are documented there, including case-insensitive label matching and the content replace semantics, so the baseline is 3. The description restates label+content and "replaces the current content" but adds no format, matching, or length guidance beyond the schema.

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

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

"Adds a custom knowledge entry ... or replaces the content of the entry with that label" gives a specific verb and names the upsert semantics, which is the key behavior an agent must understand. It also scopes itself against the sibling delete tool by name and implicitly against heliyos_knowledge_update by noting the fixed texts are kept.

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?

"Use it for facts the fixed texts do not cover, for example 'Pricing' or 'Competitors'" gives a concrete when-to-use condition, and "Remove one with heliyos_knowledge_entries_delete" routes to the alternative. It falls short of 5 because it never says when-not to use it (e.g. that editing fixed texts is heliyos_knowledge_update's job).

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 bar is lower, yet the description still adds meaningful behavior: texts are truncated at 1500 characters in concise mode, and the response is delivered as structuredContent with a named shape. It does not mention auth requirements, but for a read-only tenant-scoped fetch 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?

Three tightly packed sentences, front-loaded with what is returned and its truncation behavior. The final sentence restates the structuredContent shape that the output schema already declares, which is slight redundancy but also serves as a quick preview.

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 single-optional-parameter read tool with annotations and an output schema, the description covers purpose, truncation behavior, and the sibling routing for files. Repeating the return object fields is redundant given the output schema, but nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the enum is documented, establishing a baseline of 3, but the description adds a concrete detail the schema lacks: the 1500-character cutoff that 'concise' enforces, which is decision-relevant for choosing a format. It adds real meaning rather than restating the enum.

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 ('Returns what the workers know about the business') and enumerates the concrete contents: business context, products, pain points, value proposition, qualification criteria, and custom entries. This clearly separates it from the mutation siblings heliyos_knowledge_update and heliyos_knowledge_entries_set, and from the separate file tools.

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 a routing hint for the adjacent case: 'Knowledge-base files are listed with heliyos_files_list kind knowledge_base', telling the agent not to expect the file listing here. It does not explicitly say when to prefer this over a full record read, but the read-context is unambiguous for a knowledge-base fetch.

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 mutable, idempotent, non-destructive, and closed-world. The description adds important behavior beyond those hints: each provided text replaces the current one wholesale, omitted fields are preserved, custom entries are untouched, and workers pick up the changes on their next run. It also notes the returned structuredContent field.

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

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

The description is four tight sentences, front-loaded with the operation and affected fields, then the replacement caveat, sibling routing, and worker-visibility note. Every sentence adds useful operational context 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 five-parameter optional update tool with full schema coverage and an output schema, the description covers the important gaps: partial-update behavior, wholesale replacement risk, how to read before appending, sibling-tool routing, and when workers see the changes. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, and the schema already describes each field, including that an empty string clears it. The description lists the same field names and adds overall replacement semantics, but does not add per-parameter meaning beyond what the schema provides, so the high-coverage baseline of 3 applies.

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

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

States the specific verb and resource: it changes the knowledge base's fixed texts and names all five fields. It explicitly separates those fixed texts from custom entries handled by heliyos_knowledge_entries_set, so the agent can distinguish it from the sibling without opening either schema.

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

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

Gives explicit routing: use heliyos_knowledge_entries_set for custom entries, and use heliyos_knowledge_get first when adding to an existing text. It also explains that omitted fields are kept, clarifying partial-update behavior.

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 annotations by disclosing that the call is non-idempotent in a concrete way (calling twice creates two groups) and that activation triggers workers to start applying the label to new emails and meetings. These are real downstream side effects an agent could not infer from readOnlyHint=false / idempotentHint=false 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 action and the example, then adds the duplicate-creation warning and activation behavior in short clauses. The final "Returns structuredContent {label}" sentence is mild redundancy since an output schema exists, but nothing else is wasted.

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

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

For a 4-parameter create tool with an output schema and full annotation coverage, the description covers action, duplicate risk, activation effect and return shape. It omits whether values can be added later via labels_update and any permission requirements, minor gaps given the surrounding structure.

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

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

Schema description coverage is 100%, so the schema already documents name, values, is_active and description. The description adds only an illustrative example of name plus values; it doesn't reinforce that the required description field drives worker classification. Baseline 3 is appropriate.

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

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

Names a specific verb and resource ("Creates a classification label group with its values") and gives a concrete example (name Intent, values [Pricing, Support]). It is clearly distinguishable from heliyos_labels_list, which it routes to, but it doesn't explicitly distinguish itself from heliyos_labels_update/delete.

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 pre-condition ("check heliyos_labels_list first") to avoid duplicate groups and explains the activation condition under which workers apply the label. It lacks explicit when-not guidance (e.g., use labels_update to add values to an existing group).

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 and idempotentHint, but the description goes further by naming what is destroyed (the group and its values) and that the action is irreversible, plus a required user confirmation step. That is exactly the extra context a destructive tool needs beyond the structured hints.

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

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

Three short sentences, front-loaded with the action and its permanence, then the alternative, then the return shape. Every sentence carries information an agent would otherwise lack.

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 destructive tool, the description covers impact, irreversibility, confirmation requirement, the safe alternative, and even the returned fields. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% for the single label_id parameter, with the 24-char hex pattern documented in the schema itself. The description only restates 'by id', adding no format or validation meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Permanently deletes a label group and its values by id' — and implicitly separates itself from the update sibling. An agent can tell exactly what object this removes and what scope of data goes with 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?

Gives an explicit when-not path: to stop workers applying it while keeping it, use heliyos_labels_update with is_active false. It also adds a procedural precondition ('confirm with the user first'), leaving nothing to inference about which tool to pick.

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, non-open-world behavior, so the safety profile is covered. The description adds real context beyond that by naming the source of truth (groups workers apply to emails/meetings) and surfacing the next_cursor pagination contract. It does not state ordering of results or what happens on an invalid/stale cursor, which keeps it below 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 sentences, front-loaded with what the tool lists and followed by the return shape; nothing is padded. The second sentence partially restates what the output schema already provides, which is the only wasted weight.

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 the description need not explain return values, and annotations cover safety, so the remaining burden is purpose plus usage. Purpose and the pagination contract are covered; what an agent still lacks is result ordering and any relationship to worker configuration, which is why this stops at 4 rather than 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?

Schema description coverage is 100%, so every parameter (limit, cursor, search, is_active, response_format) is already documented in the schema, including the note about symbols causing errors. The description adds no parameter-level meaning beyond noting that values carry ids; 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?

"Lists the workspace's classification label groups ... that the workers apply to emails and meetings" gives a specific verb, a scoped resource, and the domain role of the data, with a concrete example (Intent with Pricing and Support). It is unambiguously the read-side counterpart of heliyos_labels_create/update/delete among the 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?

The listing intent is clear and the response_format enum hint implies a 'fetch then pick shape' workflow, but there is no explicit when-to-use guidance, no mention of when to reach for heliyos_labels_create/update/delete instead, and no note on whether workers must already be configured for these groups to exist. 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?

The destructive disclosure is excellent and goes well past destructiveHint=true: omitted values are removed and already-classified emails/meetings lose that label. However, the emphasized rule that a value without an id is always created as a NEW value each call means identical arguments do not produce an identical end state (old ids are dropped and classifications lost), which is at odds with the idempotentHint=true annotation.

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?

Every sentence carries a distinct, non-redundant fact, with the replace semantics front-loaded ahead of the id-preservation rule and the consequences. No filler or restatement of the tool name.

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 annotations, a full-coverage schema, and a declared return value (structuredContent {label}), the description covers what an agent needs to call this correctly. The remaining gap is the idempotency tension noted above rather than missing call mechanics.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the replace-only contract for values, the keep-by-id convention, the display format in heliyos_labels_list, and the downstream consequence for classified emails and meetings. is_active is left to the schema, which already explains 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 specific verb (changes) and a specific resource (a label group) plus the four mutable aspects (name, description, active flag, values) keyed by label_id. It is clearly distinguishable from heliyos_labels_create/delete, and it names heliyos_labels_list as the source of value ids.

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 concrete operational guidance: to keep a value, re-send it with its existing id obtained from heliyos_labels_list. What is missing is an explicit statement of when to use this tool versus create or delete a group, or what to do when the group is not found.

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

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

Annotations already declare the non-read-only, non-idempotent, non-destructive profile, and the description reinforces the idempotency consequence concretely ("Calling it twice creates two notes"). It also adds genuine value beyond annotations by disclosing the side effect that linked notes appear on records and can trigger workers. It stops short of stating permission requirements or any 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?

Three short sentences with zero filler: purpose first, then linkage semantics, then the duplicate-call warning and return shape. Nothing is buried and nothing repeats the schema verbatim.

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, the brief return-value mention is sufficient, and the atomicity and worker-trigger behavior round out what an agent needs for a three-parameter create tool. The remaining gap is that it never says how to obtain valid record ids or when to prefer updating an existing note instead.

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 titles, content format, and record id constraints are already documented in the schema, including the 24-hex id pattern and the all-or-nothing failure on unknown ids. The description confirms the records can be companies, people, or deals but adds no format or syntax detail beyond that 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?

The description opens with a specific verb and resource ("Creates a note") and immediately scopes it with optional record linking. The verb unambiguously separates it from heliyos_notes_list, heliyos_notes_get, and heliyos_notes_update without the agent needing to open 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?

Usage is only implied: it hints that linking to a company, person, or deal makes the note visible on those records and can trigger workers, which suggests why to link. There is no explicit when-to-use versus when-not guidance, and no routing to heliyos_notes_update for existing notes or heliyos_records_lookup for finding ids.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so irreversibility is partly pre-signalled; the description nonetheless reinforces it in plain language and adds the operationally important requirement to obtain user confirmation. It also previews the return payload, which goes beyond the annotations, though it says nothing about side effects on related records or how a failure (e.g., unknown id) is surfaced.

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

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

Three short sentences, front-loaded with the action and scope, then the irreversibility warning, then the return shape. No filler and nothing buried.

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

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

With a single fully documented parameter, destructive annotations, and an output schema already declaring structuredContent, most structured burden is covered and the description fills the behavioral gap (confirmation, permanence). The only missing piece is what happens to a note's associated data or attachments upon deletion, a minor gap for a delete 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 100%: note_id is documented as a 24-character hex id with a matching regex pattern. The description only restates "by id" and adds no format, sourcing, or lookup-hint detail beyond the schema, so the baseline of 3 applies.

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

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

"Permanently deletes one note by id" gives a specific verb (delete), resource (note), cardinality (one) and lookup key (id), which cleanly separates it from heliyos_notes_get, heliyos_notes_update and heliyos_records_delete. It stops short of naming a sibling explicitly, but the resource scoping makes mis-selection unlikely.

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 instruction "confirm with the user first" is a real precondition that shapes agent behavior before invocation. However, there is no guidance on when to prefer an alternative (e.g., heliyos_notes_update to modify rather than remove, or heliyos_notes_get to verify the target first), so the when-to-use context 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 cover read-only, idempotent, non-destructive, closed-world behavior, so the description is not obligated to restate safety. It adds real behavioral value instead: the 1500-character truncation under "concise" and the extra created/updated times under "detailed" are things an agent cannot learn from 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?

Three short sentences, front-loaded with the core action and followed by the format nuance and return shape. Slightly repetitive of the schema's enum wording, but nothing is wasted and nothing is buried.

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

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

For a two-parameter read tool with full schema coverage and an output schema, this is nearly complete; return structure is appropriately left to the output schema. The only gaps are edge behavior such as a missing or invalid id and whether a truncated text is flagged in the payload.

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 description's explanation of "concise" versus "detailed" nearly duplicates the enum's own schema description. With both parameters already documented in the schema, the baseline of 3 applies; the description adds emphasis but no new semantics such as whether truncation is signaled in the response.

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 ("fetches one note by id") and enumerates what comes back (title, text, linked records), which clearly separates it from heliyos_notes_list. It never names the sibling tools explicitly, so the differentiation is inferable 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?

Usage is only implied: an agent can infer this is the single-note read versus heliyos_notes_list, but the description never states when to prefer this tool or what to do if the id is unknown. No exclusions, prerequisites, or error-path guidance are 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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: default ordering (newest first), that results are truncated previews unless response_format is detailed, and pagination via next_cursor. That's solid added context, though permissions or note-visibility constraints are not discussed.

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 verb, ordering, and filters; the alternative is named early. The closing sentence enumerates the return shape even though an output schema exists, which is mild redundancy, but overall the text is tight and well ordered.

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?

Annotations cover safety, the output schema covers return values, and the schema covers every parameter, so the remaining burden is low and mostly met. The description handles ordering, preview-vs-full-text, and pagination adequately; only edge-case behavior (empty results, search error handling) is absent.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including search matching titles and bodies and the concise 200-character preview. The description restates these without adding syntax, format, or interaction details beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Lists notes") plus ordering ("newest first") and the optional filters, and explicitly marks its difference from heliyos_notes_get (full text). An agent can distinguish it from every sibling in the notes group 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?

Names the alternative tool heliyos_notes_get and the condition that selects it ("for the full text"), and implies the filtering modes available here. There's no explicit when-not guidance for search vs record_id combinations, so it falls just 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?

The annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false, so the safety profile is covered. The description adds genuine behavioral context beyond that — partial-update semantics (omitted fields kept) and the replace-not-append semantics of record_ids. It does not discuss permissions or what an empty record_ids situation would look like, and the "REPLACES links" behavior sits somewhat in tension with destructiveHint=false, though link-set replacement is reasonably read as non-destructive of the note itself.

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 with semicolons that front-loads the action and then the two non-obvious rules. Every clause carries information an agent cannot get from the name alone; nothing is padding.

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, the description needn't explain returns, and the brief "Returns structuredContent {note}" is a harmless pointer. Partial-update, replacement and validation behavior are all covered. The only gap is auth/permission expectations for a mutation 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 description coverage is 100%, so the schema already documents note_id, title, content and record_ids formats and limits, making 3 the baseline. The description does add meaning the schema lacks: record_ids is a full replacement set, not an additive one. That is a modest but real increment over the structured fields.

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?

"Changes a note's title, text or linked records by id" names a specific verb and resource and enumerates the mutable fields, so an agent can distinguish this from heliyos_notes_create, heliyos_notes_get and heliyos_notes_delete without opening the schema. It stops just short of a 5 because it never explicitly routes the agent away from those siblings (e.g. "to create a note use heliyos_notes_create").

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 clear usage context: only what you supply changes, and record_ids must contain the full desired link set rather than a delta. That is exactly the guidance an agent needs to avoid clobbering links. No explicit when-not-to-use or alternative-tool guidance is present.

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 profile is fully covered elsewhere. The description adds useful substance beyond that by noting the workspace scope and that settings can be unconfigured and that each event type carries an immediate-vs-digest frequency, but it says nothing about permissions or what happens when nothing is configured beyond the 'configured' flag name.

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 primary statement of what is returned, with no filler. The second sentence restates the output shape that the output schema already declares, which is mild redundancy but also serves as a quick scan aid.

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 read tool with full annotation coverage and an output schema, this is close to complete: the agent knows it needs no inputs and roughly what comes back. The only gap is the absence of guidance on where to go next (e.g., the update sibling) or whether specific permissions are needed to read settings.

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 explain and the baseline of 4 applies. Schema coverage is reported at 100% and additionalProperties is false, leaving nothing ambiguous about inputs.

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

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

The description names a specific verb and resource: 'Returns the workspace's notification email settings', and enumerates the facets covered (on/off, recipients, event types). It is unambiguous about scope, but never explicitly names the counterpart heliyos_notification_settings_update, so sibling routing is inferred from naming convention alone.

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

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

There is no explicit when-to-use or when-not-to-use statement, nor a pointer to the update sibling or to heliyos_organization_get/team_members_list for related config. Usage is implied by the read framing ('Returns...'), which is adequate for a zero-parameter getter but leaves guidance 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 critical behavior beyond annotations: per-key REPLACE semantics (a partial list silently drops recipients/events), omitted keys are preserved, scout.signal_detected is forced to immediate regardless of input, and the response shape is named. This is exactly the kind of data-loss risk an agent needs, since destructiveHint=false would otherwise understate the replace behavior.

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

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

Four dense sentences, front-loaded with the core action and replace warning, with the get-first workflow and the exception clause following. No filler or repetition.

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?

Output schema covers the return value and annotations cover the safety/idempotency profile, so the description's remaining job is the replace semantics and workflow — both fully addressed. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by clarifying the cross-parameter contract (each key replaces wholesale, so the full list must be supplied) and by flagging the scout.signal_detected override that the schema's enum does not reveal.

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 ('Changes the workspace's notification email settings') and implicitly contrasts with the read sibling by mandating a get-then-update workflow. An agent can distinguish it from heliyos_notification_settings_get without opening either schema.

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

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

Explicitly routes the agent to heliyos_notification_settings_get to read current values before calling, and warns that passing a key means sending the complete list. It lacks an explicit 'when not to use' clause, but the read-before-write prerequisite is clearly 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 establish the safe read-only, idempotent profile, so the description's job is to add context — and it does: it explains that 'detailed' changes the payload to include select options, hidden/AI-filled flags and relationship targets. It also notes the structuredContent shape. Minor redundancy with the output schema 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?

Front-loaded with the return contract, then the object-selection rule, then downstream tool routing — a sensible order. It is dense rather than padded, though the run of sibling tool references (records_create/update/list, fields_create/update/delete) compresses a lot into one paragraph.

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 full schema coverage, annotations, and an output schema, the description covers selection rules, response modes, error fallback for custom schemas, and follow-up tools. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, giving a baseline of 3. The description reinforces the custom/schema_id dependency and clarifies that 'detailed' surfaces allowed select values and flags, but adds little syntax or constraint detail beyond the schema.

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

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

Opens with a specific verb and resource: 'Returns one object's fields', then enumerates exactly what each field carries (key, label, type, required) and what 'detailed' adds. It is clearly distinguishable from heliyos_objects_list (which supplies schema_id) and from the field-mutation siblings it feeds.

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 states how to pick the object (object_type, with custom requiring schema_id from heliyos_objects_list) and routes the returned field_id to heliyos_fields_update/_delete and new fields to heliyos_fields_create. What's missing is an explicit disambiguation from heliyos_records_get / heliyos_records_list, which an agent might confuse with schema inspection versus record data.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: every object comes back in a single page (a workspace has a handful), so no pagination is needed, and results arrive as structuredContent {objects}. What is missing is only minor, e.g. nothing about ordering or error behavior.

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

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

Three sentences, each earning its place: what it lists, how to use the output, and the return shape. The identity of the tool and its return shape are front-loaded before the routing advice.

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 single optional-enum parameter tool with an output schema and full annotation coverage, this is sufficient: the agent knows what comes back, that there is one page, and which tools to chain into. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the response_format enum already documents the concise vs detailed difference in the schema itself, so the description need not restate it. The description adds no parameter-level meaning beyond what the schema provides, which is the correct baseline at full coverage.

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

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

States a specific verb and resource and enumerates what is returned: 'Lists the workspace's objects (record types): companies, people, deals and any custom objects'. It also contrasts with the sibling heliyos_objects_get, so an agent can tell the list tool from the get tool without opening either schema.

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

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

Gives explicit downstream usage: use it to learn which object_type and schema_id to pass to heliyos_records_*, notes that custom objects need schema_id, and points to heliyos_objects_get for field keys. Both the purpose and the alternative are named, leaving nothing 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description still adds value beyond them by disclosing the implicit scope (the workspace bound to the calling API key, no lookup parameter needed) and the response shape via structuredContent {organization}. It stops short of covering error or auth-failure behavior, so a 4 rather than 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?

Three sentences, front-loaded with the return payload and then the routing guidance; nothing is wasted. The long enumeration of returned fields overlaps with the existing output schema, which makes it slightly heavier than strictly necessary, but it remains scannable and purposeful.

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 trivial, side-effect-free orientation call with a full output schema and complete annotations, the description covers everything an agent needs: what it returns, that it should come first, and where to go next for adjacent data. No gaps remain that would cause a mis-invocation.

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 no parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly communicates that scope comes from the API key rather than from input, which is the only semantic question this zero-parameter signature raises.

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 ("Returns the Heliyos workspace this API key belongs to") and then enumerates the concrete data returned: id, name, billing status, plan, member count, company/person/deal counts, and watchlist usage against plan limit. This is clearly distinguishable from siblings like heliyos_usage_get or heliyos_objects_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?

Gives an explicit ordering instruction ("Call it first to orient yourself") and names two alternatives with the conditions that select them: heliyos_objects_list for objects and schema ids, heliyos_usage_get for credit usage. An agent knows both when to use this tool and which sibling to pick 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?

The annotations already declare non-idempotent, non-read-only, non-destructive behavior. The description adds valuable side-effect context not in annotations: duplicate calls create duplicate records, and creating a company can trigger automatic enrichment that consumes credits. It does not cover permission or error details, but the description carries the key behavioral risks well.

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 are front-loaded with the action and the duplicate-check warning, and each sentence carries useful information. The final sentence about return value is somewhat redundant because an output schema exists, but it does not undermine clarity.

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 create tool with a nested fields object and an output schema, the description covers the critical operational context: what it creates, duplicate risk, and the enrichment side effect. The schema handles the fine-grained field requirements, and the annotation profile is already covered, leaving little missing for correct invocation.

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 input schema already explains object_type, fields, relationships, and schema_id in depth. The description adds little parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: creating one record, with the concrete object types (company, person, deal, custom object row). This distinguishes it clearly from sibling tools such as heliyos_records_lookup and heliyos_records_update without opening 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?

It gives explicit when-to-use guidance by instructing the agent to check heliyos_records_lookup first to avoid duplicates, and it warns that calling twice creates two records. That is direct routing to an alternative tool and the condition that selects it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value beyond them: irreversibility, the fact that ids from other objects are silently ignored, and the important caveat that deleted_count reflects ids sent rather than confirmed deletions.

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 action and its limit, then the safety warning, then the return shape. No filler and no repetition of schema 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 destructive batch tool, it covers the essentials: the 100-record cap, the object_type/record_ids coupling, irreversibility, and the return payload. An output schema exists, yet the description's note about deleted_count semantics is still the key detail an agent needs.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining cross-parameter semantics the schema cannot: all record_ids must belong to object_type, and mismatched ids are ignored without an error or count confirmation.

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 scope: "Permanently deletes up to 100 records of one object by id." The batch cap and single-object constraint distinguish it from sibling delete tools (notes_delete, tasks_delete, fields_delete) and from records_update.

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 one explicit usage directive — "confirm with the user first" — which is valuable for a destructive operation. However, it never names alternatives (e.g., records_update to modify instead of delete) or states when-not to use it, so routing guidance is only implied.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavior beyond that: sort order (newest first), per-event shape (one-line change summary, actor can be a person or a worker), and that response_format='detailed' enlarges each entry with changed field paths. It does not discuss rate limits or maximum result depth, which is the remaining gap.

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 and dense: core behavior first, then filtering, then the mode flag, then the sibling routing. The closing return-shape sentence is largely redundant given a full output schema exists, which is the one sentence that does not fully earn 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 9-parameter read tool with annotations and an output schema, it covers intent, ordering, filtering, pagination via next_cursor and mode behavior. Nothing needed to call it correctly is missing, though it repeats the structuredContent shape that the output schema already defines.

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

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

Schema description coverage is 100%, so the schema already documents limit, cursor, since/until, search, event_types, operation_types and response_format. The description only restates the available filter axes and the 'detailed' behavior, which the response_format schema description already says. Baseline 3 is appropriate because the schema carries the semantic load.

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 ('returns the audit trail of one record') and immediately scopes the payoff: who changed what, when, newest first, with one-line summaries. It also names the sibling it is not (heliyos_records_timeline) so an agent can separate event history from a narrative timeline without opening either schema.

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

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

Explicitly routes the agent away from this tool when it wants a narrative of the relationship, naming heliyos_records_timeline as the alternative. It gives no guidance on the other close neighbors (heliyos_records_get for current field values, heliyos_tasks_events for task history), so the exclusion set is only partially drawn.

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 non-destructive behavior, so the safety profile is covered. The description adds real behavioral context the annotations cannot: what the two response modes actually return, including that detailed includes linked records with ids plus created/updated timestamps. It omits error behavior for unknown ids.

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 front-loaded sentences: purpose, sequencing, then return modes. Every sentence carries content, with no restatement of the title. The final sentence is dense but still readable.

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 only two parameters, a 100% schema and a declared output schema, this is close to complete. It explains the mode tradeoff an agent needs in order to choose correctly. Only edge cases such as invalid id or not-found handling are absent, and those are 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 100%, so the baseline is 3. The description still adds meaning beyond the schema by spelling out what concise counts (linked records) and what detailed expands to (linked records with ids, created and updated times, with a person's company / company's deals as concrete examples).

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

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

The description names a specific verb and resource ("Fetches one record") and enumerates the record types it covers (company, person, deal, custom object row), which helps an agent distinguish it from list/lookup. It does not explicitly contrast its own return with heliyos_records_lookup, so the sibling boundary 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?

It gives an explicit sequencing rule: call it after heliyos_records_list or heliyos_records_lookup yields an id. That routes the agent correctly among the 70 siblings. It does not state when not to use it (for example, when a timeline or events call is more appropriate).

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, non-destructive and non-open-world, so the safety profile is covered. The description adds behavior beyond that: newest-first default ordering, the exact pagination loop ("when next_cursor is present, call again with `cursor` set to it"), and the concise/detailed return distinction. It does not mention permissions or rate limits, which keeps it at 4 rather than 5.

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

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

Four front-loaded sentences: purpose, sibling routing, parameter grouping, and return/pagination. Everything is dense and usable, though the return-shape sentence duplicates what the existing output schema already declares, which is the one place words could be trimmed.

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 9-parameter, nested-filter, paginated list tool with an output schema, the description covers purpose, alternatives, parameter grouping, pagination continuation, and downstream id usage. Nothing needed to call it correctly is missing, and return values being explained is a bonus rather than a gap since an output schema 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 100% and every parameter, including the nested filter operators and the sort object, is documented in the schema itself. The description only restates the cross-parameter linkage ("filters (field conditions joined by `match`)") without adding syntax, value formats, or edge cases beyond what the schema already says. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

"Lists records of one object (companies, people, deals, or a custom object) in the Heliyos workspace, newest first" names a specific verb, the resource, the allowed object scopes, and the default ordering. It explicitly contrasts itself with heliyos_records_lookup (find by name) and heliyos_records_get (single record), so an agent can distinguish it from the nearest siblings without opening a schema.

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

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

The description states the browse/filter use case and then routes the agent away: use heliyos_records_lookup to find a record by name and heliyos_records_get for one record. It also gives the within-tool selection logic for `search` vs `filters` vs `sort`, and closes by noting that returned ids feed _get, _update and _delete, which tells the agent what to do next.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. Beyond that the description discloses traits annotations cannot: a hard search scope of the 2000 most recently updated records, the ranking order (exact and prefix first), and which secondary field is consulted. The only minor omission is that it does not restate how limit/response_format shape the result set, though it does name the return payload.

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: capability and ranking first, purpose second, scope limit and fallback third. Parenthetical asides carry genuine information rather than hedging, and no sentence is redundant with the schema or annotations.

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 5-parameter read tool with a full output schema, the description covers purpose, matching semantics, the search-window limit, the fallback path and even the return shape. Nothing an agent needs to call it correctly or decide against it is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds real meaning by explaining that matching is case-insensitive, that exact and prefix matches rank first, and that query falls back to a secondary value (first of domain, email, job title or stage). That goes beyond the schema's plain "Name or part of a name".

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

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

It opens with a specific verb and resource ("Finds records of one object") and immediately narrows the match predicate to name-contains or secondary-value-contains, with ranking rules. An agent can tell it apart from heliyos_records_get (exact retrieval) and heliyos_records_list (enumeration) 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?

It states the intended job explicitly ("Use it to turn a name the user mentions into a record id") and gives a concrete exclusion plus alternative: older records outside the 2000 most recently updated require heliyos_records_list with search. That is an explicit when/when-not/alternative triple.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond that: entries are AI-written, ordered newest first, paginated via next_cursor, and shaped as structuredContent. It stops short of saying how fresh or complete the AI summary is, which keeps it below 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?

Three sentences, front-loaded with what is returned, then when to use it, then the disambiguation. Every clause carries information and there is no restatement of the title or name.

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, the description does not need to explain return values, yet it still names the structuredContent fields as a convenience. Combined with explicit sibling routing and pagination notes, an agent has everything needed to call this correctly on the first attempt.

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 record_id format, limit bounds, cursor reuse, and the concise/detailed truncation tradeoff are all already documented in the schema. The description only reinforces cursor pagination and newest-first ordering, adding little syntax or semantic meaning beyond the structured fields.

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 ("Returns the AI-written timeline of one record"), scopes it to company/person/deal, and enumerates the payload (relationship summary plus dated entries for emails, meetings, deal moves). It explicitly names the sibling tools it is not, so an agent can separate it from heliyos_records_events and heliyos_interactions_list without opening a schema.

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

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

Gives a positive use case ("brief yourself on an account before acting") and two explicit alternatives with the condition that selects each: raw field-change audit goes to heliyos_records_events, and the underlying emails/meetings go to heliyos_interactions_list. Nothing about routing is left to inference.

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

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

Annotations only declare readOnly=false, idempotent=true, destructive=false; the description goes well beyond that by disclosing merge semantics ('fields you leave out keep their values'), the null-to-clear convention, key validation that rejects unknown keys and returns the valid set, and that `relationships` only adds links and never removes them. It also states the return payload shape. This is exactly the mutation-specific behavior an agent needs before writing.

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, front-loaded sentences that each carry operational information, starting with the core verb+scope before the field-level rules. Minor redundancy with the `fields` schema description for the relationships behavior keeps 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 two-parameter mutation with nested `fields` and an output schema, the description covers everything an agent needs: id sourcing, merge vs clear semantics, validation failure mode, link accumulation, and return contents. Nothing material is left to inference.

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 a 3 is the baseline, but the description adds meaning the schema does not: omitted keys are preserved and explicit nulls clear a field. The `relationships` and unknown-key semantics are largely restated from the `fields` schema description, so the gain is real but modest.

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 plus its precise scope: 'Updates some fields of one record by id', which immediately signals a partial (merge) update rather than a full replace. It also names heliyos_records_list and heliyos_records_lookup as the id sources, so an agent can distinguish it from the read siblings without opening a schema.

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

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

Gives clear operative context: get the id from heliyos_records_list or heliyos_records_lookup before calling, and omit fields you don't want changed. It stops short of explicit exclusions — it never contrasts itself with heliyos_fields_update (schema/field definitions) or states what to do when the record doesn't exist.

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