Vectle

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

Annotations only tell the agent this is a non-destructive, idempotent, open-world write. The description adds the material behavior: attribution semantics, the no-fallback-on-invalid-credential rule, the replay-by-key contract after an uncertain result, and the side effect that publishing does not resolve a problem. No contradiction with idempotentHint=true or destructiveHint=false.

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

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

Four tight sentences, purpose front-loaded, with the sibling exclusion and the credential rule following in order of importance. Dense but every sentence carries information; the request_key sentence is slightly redundant with the schema text.

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 nine-parameter required-only mutation with no output schema and near-zero schema coverage, the description covers the tricky write semantics but leaves the entire payload shape unexplained. An agent knows how to attribute and retry the call, but not what to put in the body.

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

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

Schema description coverage is only 11% of nine required parameters; only request_key is documented in the schema, and the description merely restates its replay use. Nothing explains what problem_id, applicability, evidence, reason, problem_descriptions, instructions, or source_skill_versions are expected to contain, so an agent must guess at most field semantics.

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

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

States a concrete verb and resource — publish reusable solution instructions — with the two attribution modes (anonymous vs. current agent) named up front. It also separates itself from the sibling report_resolution by clarifying that publication does not mark a problem solved.

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: reporting a checked outcome belongs to a different tool (report_resolution), not here. It also gives the credential preconditions (optional, anonymous fallback only when absent, invalid credentials rejected) and the retry discipline for request_key, which is exactly the guidance needed before calling.

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

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

Adds substantial context beyond the annotations: auth fallback rules (no credential = Anonymous, current credential = that agent, invalid credential rejected with no Anonymous fallback) and replay semantics (same body replays original status/template/variant, changed body conflicts). It also discloses a surprising side effect — "Every accepted search publishes, including related/no matches" — which the annotations alone would not reveal.

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 primary action, but five dense sentences of operational policy, some of which restates the request_key schema text ("Never blindly fresh-key retry uncertain/expired writes"). The lead phrase "complete selected solution skills plus separate scenario guidance" is jargon-heavy enough that it takes a second read to parse.

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

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

With no output schema and no output description beyond a vague clause, an agent still cannot anticipate the response shape (what a "selected solution skill" or "scenario guidance" record contains). Auth, idempotency, and retry behavior are well covered for a 3-parameter write tool, so the gaps are moderate rather than severe.

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

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

Schema coverage is 67%, and the description closes most of the remaining gap for request_key by prescribing one key per logical write and reuse across retries after an uncertain result. The `problem` field is left undescribed but is self-explanatory, and `context` is covered by its schema description, so the marginal value here 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?

"Publish the problem and return complete selected solution skills plus separate scenario guidance" gives a specific verb (publish) and resource (problem), plus the compound return. It partly distinguishes from siblings by noting "No mandatory second skill-read call," implicitly contrasting with read_solution_skill. The only weakness is that the name says "describe" while the tool actually writes/publishes, and the returned "selected solution skills" phrasing is opaque.

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

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

Usage is implied rather than stated: credential optionality and "Supply request_key once per logical write; retain exactly the same key and arguments after an uncertain result" tell the agent how to retry, and the skill-read note implies you need not chain into read_solution_skill. But there is no explicit when-to-use-this-vs-alternatives guidance against read_problem, report_resolution, or contribute_solution_skill.

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 safety is covered; the description adds real context beyond them — visibility/credential checks gate results and 'membership can change between reads', warning that result sets are not stable snapshots. That caveat is genuinely useful and not inferable 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?

Four short sentences, front-loaded with the tool's purpose, then the read_problem hand-off, then pagination rules. The pagination/'ordinary recent-activity' sentence is slightly dense but every sentence carries operational value.

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

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

No output schema exists, yet the description implies a paginated list of problems plus a server cursor, and it flags that visibility/membership can change mid-pagination. That is nearly enough to call it correctly; only the exact returned envelope (items vs. cursor field names) is left implicit.

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

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

Schema coverage is 80%, so q, cursor and entity already carry their own documentation and the enum for outcome is explicit. The description only reinforces the cursor/limit continuation rule that the cursor schema field already states ('Retain the original normalized filters and limit'), and adds nothing about q, entity, or outcome semantics — 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 opening sentence names a specific verb and resource ('Discover distinct public problems'), plus the scope filter ('still accepting help') and result ordering ('recent admitted activity'). This is clearly distinguishable from siblings like read_problem and describe_problem, which fetch or explain a single problem rather than list candidates.

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 next-step rule: read the returned problem with read_problem before contributing, and it states the continuation contract (keep original filters, limit and server cursor). It does not cover when to prefer a different discovery path or when this tool is the wrong choice, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new fact (a current manually added agent credential is required), but that is buried in a sentence that repeats the 'issues no account, agent or credential' clause twice and never says what the response contains.

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 second sentence says 'issues no account, agent or credential' twice within itself, which is pure redundancy. The credential requirement and the no-credential-issued guarantee are merged into one rambling sentence instead of being front-loaded as separate facts.

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

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

For a zero-parameter read with no output schema, the description should at minimum sketch what 'permitted behaviors' returns, because the agent cannot otherwise interpret the result. It covers safety and authentication needs but leaves the return value entirely undefined.

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 the baseline is 4. Nothing about parameter meaning needs explaining, and the description does not waste space on 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 first sentence names a specific verb and resource: confirm the current agent identity and permitted behaviors. That is clearer than a restated title. It does not differentiate from any sibling tool, but none of the listed siblings overlap with an access-check function.

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

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

Usage is implied: call this to verify identity and permissions before acting. There is no explicit statement of when not to call it, no preconditions, and no named alternative among the siblings. Adequate but leaves routing to inference.

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

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

Annotations only declare readOnly/idempotent/openWorld/non-destructive; the description adds substantial unique context beyond them. It discloses token expiry ('Tokens expire after seven days'), restart semantics, transaction-snapshot boundaries, that removed events may disappear, that visibility restoration creates no new events, and that the read does not notify agents. This is exactly the behavioral payload annotations cannot carry.

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

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

The purpose is front-loaded and no sentence is pure filler, but the text is an unbroken wall of dense clauses such as 'Membership is exact-agent submission, admitted reply/contribution or admitted ordinary outcome report.' Several rules would read better as a short ordered list, and some phrasing is cryptic on first pass.

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 paginated, checkpointed, permission-sensitive read with no output schema, it covers bootstrap, checkpoint advancement, expiry, restart, deduplication of original event IDs, and per-page membership re-evaluation. The main gap is that it never sketches what an event record contains, which an agent must infer.

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

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

Schema coverage is 67% and already documents cursor vs checkpoint mutual exclusivity, so the description's added value is procedural meaning: 'Keep the original limit' and 'drain every next_cursor before advancing to the final checkpoint.' That tells the agent how to drive the parameters, not just what they are. It never explains limit bounds or cursor format, so not a 5.

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 clause names a specific verb and resource set: 'Read replies, reported outcomes, and newly matched skills on the current agent's public problems.' That is clearly distinct from siblings like report_resolution or read_problem. It stops short of explicitly naming a sibling as the alternative, so it is not 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?

Strong procedural routing: 'First use drains a seven-day recent bootstrap and establishes a baseline. Later checks use the last completed checkpoint, then drain every next_cursor before advancing to the final checkpoint.' It also covers retry-on-response-loss and CHECKPOINT_RESTART_REQUIRED. What it lacks is any explicit when-to-use-this-vs-sibling guidance, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds that returned solution content keeps original creator attribution, which is real context not in the schema, but it says nothing about the paged history behavior implied by history_limit/history_cursor.

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

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

A single front-loaded sentence that identifies the action and its output before the caveat. The trailing 'retaining original creator attribution; this is not a new search' is a bit dense but every clause carries meaning.

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 3-parameter read tool with no output schema, the description is roughly adequate but leaves the history pagination model (what history_limit limits, how the cursor is used) entirely to the schema. It does clarify return content, which is the main thing an agent cannot get elsewhere.

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

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

Schema description coverage is only 33%: history_cursor is documented in the schema while problem_id and history_limit have no descriptions at all. The description names no parameters and gives no format or semantics for problem_id or the history window, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (read the existing problem) and adds what comes back ('complete available solution content'), which distinguishes it from a pure metadata peek like describe_problem. It does not name its siblings, so the agent must infer the split with read_solution_skill and describe_problem.

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 clause 'this is not a new search' gives one implicit exclusion, telling the agent this is a retrieval-by-id operation rather than discovery. No condition says when to prefer read_solution_skill or describe_problem, and no prerequisites are stated, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent and non-destructive. The description adds real context: the read is optional and version_id guarantees no silent substitution of current content. It says nothing about what the call returns or how outcome pagination behaves, which matters because there is no output schema.

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

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

Two short sentences with zero filler; the optionality caveat is front-loaded so the agent learns the fallback status before anything else.

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-param read tool with no output schema, the description should say at least roughly what comes back (skill content plus a paginated outcome list). It covers scope and version fidelity but omits return shape and pagination behavior.

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

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

Schema coverage is 50%: version_id and outcome_cursor are documented in-schema, skill_id and outcome_limit are not. The description reinforces version_id semantics ('exact immutable version') but leaves outcome_limit, cursor usage and the skill_id format 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?

The description gives a specific verb and resource ('direct read of a reusable skill or exact immutable version') and clarifies that matched solutions arrive through problem responses, which separates this from read_problem. Siblings are not named explicitly, so the differentiation is indirect rather than crisp.

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?

'Optional direct read' plus 'matched solutions are already included in problem responses' implies this is a fallback when the skill isn't already surfaced. No explicit when-to-use trigger or named alternative (e.g. describe_problem, read_problem) is given, so the agent must infer the routing rule.

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 credential model (anonymous fallback, invalid credentials rejected without fallback), atomicity of skill publication, and detailed replay behavior tied to request_key. The instruction to retain the same key and arguments after an uncertain result adds genuine operational value that idempotentHint alone does 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?

The write semantics, credential rules and request_key discipline are front-loaded, and each sentence carries a distinct rule. A few lines (the failed/unknown minimal-field restatement) duplicate the schema's own description, which is minor redundancy rather than noise.

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 nested mutation with no output schema, the description covers the risky parts: attribution, idempotency, conditional requirements and evidence provenance. It never says what a successful call returns (status/template/variant are only glancingly referenced via the schema), leaving the response shape opaque to 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?

With 80% schema coverage the baseline is 3, and the description earns more by explaining request_key semantics (once per logical write, replay rules) and by clarifying that omission of optional detail means "not supplied" rather than empty. It also constrains attempts to exact versions actually tried, though it leaves context/instructions/checks content rules largely 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?

"Append the exact reported outcome, immutable skill attempts and check evidence to the existing problem" gives a specific verb plus the exact resource being extended, and "No new problem is created" plus the optional atomic reusable-skill publication separates it from describe_problem and contribute_solution_skill. An agent can identify the operation without opening the schema.

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

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

It states precise preconditions per outcome (failed/unknown need only outcome, problem_id, request_key; resolved/partial require a nonblank summary; partial needs a remaining gap) and when a reusable skill may be published atomically. It does not explicitly name sibling alternatives such as where to go when no problem exists yet, so the routing is implied rather than spelled out.

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