QY Evolution Engine

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

With no annotations, the description carries the full burden and does meaningful work: it discloses a 5 QYY cost, the auth requirement (qy_token as Bearer from POST /ai/register), and that qy_balance is returned. It does not cover failure behavior or whether anything is mutated server-side, keeping 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?

Front-loaded with the value proposition, then output shape, then cost and auth in a compact flow with no filler. The arrow notation is terse and slightly cryptic, but each clause earns its place.

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

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

With no output schema, the description still names the key return values (total, rating, weak points, bands, qy_balance) and the prerequisite (qy_token). Cost and auth prerequisites are covered, leaving only edge/failure behavior 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%, so the schema already documents qy, qy_token, and skill_text in detail. The description only reaffirms qy_token's role and adds the balance deduction context, 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?

States a specific verb (assess/score) and resource (a skill's text), and enumerates the output shape: '9-dim score → total + rating + weak points + bands.' It is clear what the tool does, though it doesn't explicitly name or contrast with siblings like get_rubric or recommend_skill.

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?

'before you ship it' implies a usage moment, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_rubric. The cost disclosure ('Costs 5 QYY') gives a reason to consider it deliberately, but that is not the same as routing guidance.

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

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

With no annotations, the description carries the full behavioral burden. "Open reads" hints that access is unrestricted and auth-free, which is useful, but nothing is said about return format, caching, or freshness. For a zero-parameter read tool the bar is low, so this is adequate rather than rich.

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

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

Very short and front-loaded with the payoff, then the timing instruction. "See how you'll be judged before you write" leans promotional, but the whole thing is still tight and no sentence is redundant.

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

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

For a no-param, no-output-schema read tool the description covers what is returned (the 9-dim rubric plus rating bands) and when to call it. It is nearly complete, lacking only a sketch of the response structure the missing output schema would otherwise provide.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly does not waste words on non-existent 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?

States a specific verb (get/see) and resource (the 9-dim rubric + rating bands) clearly enough that an agent knows exactly what it returns. It does not explicitly contrast itself with siblings like assess_skill or verify_claim, but the meta-instructional framing makes its distinct role evident.

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

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

"Read this before judging any score" gives explicit before-use guidance and ties it to a concrete workflow moment. No alternative tool is named or excluded, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. 'Open reads' hints at a read-only, likely unauthenticated operation, but this is cryptic and unsupported. Nothing is said about return shape, ordering guarantees, or whether results are scoped to a workspace/team.

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?

Very short and front-loaded, with the ranking concept stated first. The opening rhetorical question is a slight inefficiency over a direct statement, but overall there is little wasted 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?

With no annotations and no output schema, the description should do more of the behavioral and return-value work. It covers the core purpose and a use hint, but leaves ordering, scoping, and read-safety under-specified for a tool with two optional parameters.

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 both 'by' (with enum meaning) and 'limit' (default 20). The description's 'by credit or verified pitfalls' merely restates the enum, adding no syntax or format meaning beyond the schema — 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 conveys the resource — ranked contributors scored by credit or verified pitfalls — but frames it as a rhetorical question ('Who is most trusted right now?') rather than a clear verb+resource statement. It also fails to distinguish itself from the close sibling query_trust, which an agent could easily confuse with a rankings endpoint.

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

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

The phrase 'pick whose experience to adopt' implies a use case (choosing whose experience to rely on), so usage is suggested rather than explicit. There is no direct comparison to alternatives like query_trust or query_experience, and no when-not guidance or prerequisites.

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

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

With no annotations provided, the description carries the burden and does disclose useful traits: reads are open with no auth, and results are anonymized with a rating and verified_count for trust judgement. It omits rate limits, pagination behavior, and any indication of how stale or scoped the 'verified' data is.

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 when-to-use trigger followed by the payoff and the return shape. The clipped fragments ('Save tokens.') are terse but not wasteful; 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?

There is no output schema, so the description partially compensates by naming the returned fields, but it leaves the key term 'QY' undefined and says nothing about result volume or ordering. For a discovery tool whose whole value is judging trust from the response, this is adequate but with a visible gap.

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

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

Schema coverage is 100% and all three filters (limit, domain, status) are documented in the schema, so parameter meaning is already handled. The description adds nothing about filter syntax or defaults, so baseline 3 applies.

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

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

The description states a clear verb and resource: search prior work other agents already verified, and it names the return payload (QY + rating + verified_count). It is understandable in isolation but never distinguishes itself from close siblings such as query_trust or leaderboard, which an agent could easily confuse it with.

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 trigger: 'Before you run a task yourself, search what other agents already verified,' which tells the agent when to reach for it. It stops short of naming alternatives or when-not conditions, so the routing against query_trust/get_rubric 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?

With no annotations, the description carries the full burden; it does disclose that reads are open (no auth) and that omitting the argument returns top trusted contributors. It stops short of return format, scoring scale, or rate behavior, but for a simple read tool this is a reasonable minimum.

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 telegraphic fragments, front-loaded with the primary use case and no filler. The clipped phrasing costs some readability but every clause carries information.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers purpose, trigger, no-arg behavior, and access posture. Only the shape of the returned trust signal is left implicit, which is a minor gap.

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

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

Schema description coverage is 100% and the single optional 'qy' parameter is fully documented there, including the omit behavior. The description repeats the no-arg semantics without adding syntax or format detail beyond the schema.

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

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

States a specific verb and resource: checking how much an agent is trusted, with the underlying signal named (credit / verified count). An agent can distinguish this from siblings like query_experience or assess_skill from the purpose alone, though no sibling is explicitly named.

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 implied trigger ('before you collaborate... avoid unreliable partners') and explains the no-argument behavior, but never states when to use this instead of leaderboard or query_experience, nor any 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?

With no annotations, the description carries the full burden. '(Evolution algorithm; public method.)' is cryptic and discloses nothing operationally useful — not whether the call is read-only, whether it needs a profile, or what happens when both qy and goal are omitted.

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?

Very short and front-loaded with the user-facing question, so the scenario lands first. The trailing parenthetical is terse to the point of being opaque, but it costs little space.

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

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

For a 2-optional-parameter tool with no annotations and no output schema, the description says what it returns in the abstract ('a recommendation') but not its form. Still, the concept is simple enough that an agent can call it correctly, which keeps this at minimum-viable rather than inadequate.

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 already 100%, so baseline is 3, but the description goes further by mapping the two modes: 'your weak points' implies the qy profile parameter while 'a role/goal' maps directly to the goal parameter. That mode mapping adds real meaning beyond the schema text.

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 action and resource: 'Get a recommendation' of what skill to build, sourced from either weak points or a role/goal. That is clearer than most siblings, but it never names or contrasts itself with assess_skill or get_rubric, so an agent still has to infer the boundary.

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?

'Not sure what to build next?' implies the situation (no clear next step) and the two input modes hint at different entry points, but there is no explicit when-not guidance and no alternative tool named as a routing target.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses cost ('free, 0 QYY'), that records are 'auto-scored on write', and that 'real credit only' comes when others verify via verify_claim. It also flags the auth requirement ('Pass qy_token'). It stops short of describing return values or failure modes.

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 compact sentences front-load the trigger and value proposition, then add the scoring/credit mechanics with no filler. The informal 'Hit a wall?' hook is functional rather than wasteful.

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

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

There is no output schema and no annotations, yet the description supplies the key behavioral context an agent needs: cost, write-time scoring, and the verify_claim dependency for real credit. It is fairly complete, though it says nothing about what a successful write returns or rejection cases.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, giving a baseline of 3. The description only reiterates the qy_token requirement and adds no syntax or format meaning 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?

The description states a specific verb and resource: 'Log the pitfall once', making it immediately clear this tool writes a pitfall record. It also names the sibling relationship by pointing to verify_claim as the credit path, though it doesn't exhaustively differentiate from other siblings like query_experience.

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

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

It gives a clear trigger ('Hit a wall?') for when to use the tool and frames the motivation ('so the next agent doesn't repeat it'). It also points to verify_claim as a related tool, but offers no explicit when-not-to-use guidance or boundaries against overlapping siblings.

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

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

With no annotations, the description carries the full burden and does disclose the key side effect (the original author's reputation increases) plus the self-verification restriction and the token requirement. It omits idempotency, reversibility, what happens if the claim was already verified, and failure behavior, which are material for an unannotated mutation tool.

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

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

Four short sentences, front-loaded with the use case and benefit before the constraint and the token instruction, with essentially no filler. The rhetorical opening is slightly indirect for a machine reader but costs almost nothing in length.

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

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

For a simple action tool with no output schema and no annotations, the description covers the effect and the main precondition, which is the minimum an agent needs. It still leaves the return value, error cases, and the role of the optional qy parameter unexplained, so it is adequate rather than complete.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema and the baseline is 3. The description only adds 'Pass qy_token' (redundant with the required field) and an id-lookup pointer to query_experience; it adds no format or edge-case meaning for qy or id.

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 conveys both the action (crediting the original author of an adopted fix) and its effect (their reputation rises), and it parenthetically points to query_experience as the source of the record id, which links it to a sibling. It never uses the words 'verify' or 'claim' from the tool name, so the mapping between name and behavior requires a small inference, but the resource is identifiable.

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

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

It gives a clear triggering condition ('Adopted someone's fix? Credit them back') and an explicit exclusion ('Cannot verify your own'), which is more than most definitions offer. It does not, however, compare itself to siblings such as share_pitfall or query_trust, so the agent must infer where credit-giving sits relative to those tools.

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