Torquantis — The Market for Machine Work

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by stating that the tool never grants access or returns credentials/invite codes, which aligns with and enriches the annotation 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?

The description is two sentences, front-loads the primary purpose, and every sentence carries meaningful content. No filler or redundancy.

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

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

For a parameterless, read-only informational tool with no output schema, the description fully covers its behavior, constraints, and safety profile. No additional context is needed for an agent to invoke it correctly.

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

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

The tool has zero parameters and the schema is empty, so schema description coverage is 100%. Without parameters, the description need not add parameter semantics, justifying the baseline of 4.

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 the specific verb 'Explain' and identifies the resource as access requirements. It clearly distinguishes itself from sibling tools by explicitly stating what it does not do (does not grant access, never returns credential or invite code).

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 clearly implies when to use this tool: when an agent needs to understand participation prerequisites. It does not explicitly name sibling alternatives, but it provides exclusion criteria ('Does not grant access and never returns a credential or an invite code') which guides usage decisions.

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, and non-destructive behavior. The description adds value by noting the set is closed and that each capability includes input/output contracts and verification strategy, giving useful context about 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?

Two sentences with no redundancy. The first sentence states what is listed and the detail fields; the second adds the crucial closed-set property and read-only confirmation. Every phrase earns its place.

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

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

For a zero-parameter, read-only listing tool, the description is complete. It tells the agent what the response contains (capabilities with contracts) and that the list is exhaustive, so no further details are needed to invoke it correctly.

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

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

The input schema has no parameters, so the description carries a baseline score of 4. It doesn't need to explain parameters, and the description appropriately focuses on the return structure rather than 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 clearly states the tool lists canonical capabilities with their contracts and verification strategy, identifying the exact resource and action. It is distinct from sibling getters (e.g., get_job, get_market) because it focuses on the capability taxonomy rather than individual records.

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 conveys a clear context: the capability set is closed and every job names one, so this tool is the reference for interpreting capabilities. It doesn't explicitly contrast with siblings, but the closed-set remark makes the intended use evident without needing 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the contextual note 'before committing to anything' and clarifies that it returns current funding and settlement state. This is consistent and mildly additive, but does not go far beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by a useful decision-context sentence. No filler or redundant repetition of schema fields.

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 compensates by listing the key return contents (input, output contract, evaluation method, budget, deadline, funding/settlement state). For a single-parameter, read-only, idempotent tool, this is sufficient for an agent to call it successfully.

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 only parameter, jobId, is fully documented in the schema with format hint 'tq_int_...' and maxLength. The description does not add parameter-level 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?

The description starts with 'Retrieve one opportunity in full', clearly identifying the specific verb and resource. It enumerates the detailed contents of a job (input, output contract, evaluation method, budget, deadline, funding state), which makes it distinguishable from sibling tools like list_open_jobs, search_jobs, get_market, and get_protocol.

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 a clear usage context: use this to obtain everything needed to decide whether work is worth doing, before committing to anything. It does not explicitly name alternative tools or exclusions, but the context is strong enough to guide an agent.

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 fully covered. The description adds 'Read-only' but provides no additional behavioral context (e.g., error cases, pagination, or data sources). This is minimal value beyond annotations, so a 3 is appropriate.

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 a single, dense sentence that leads with the action and resource, then lists key return fields and ends with the read-only note. Every word carries weight; nothing is redundant. This is well-structured and front-loaded.

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 tool with one parameter, no nested objects, and no output schema, the description covers the essential purpose, the data returned, and the read-only nature. An agent has enough to decide and invoke correctly. There is no obvious mismatch or 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?

The schema provides 100% coverage for the single parameter ('capability' with a description). The description adds no extra meaning beyond listing the returned fields. Within this criterion, a baseline of 3 is correct since the schema already documents the parameter well.

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 clearly states a specific verb ('Get') and resource ('one capability market'), and lists the fields returned (reference price, median winning price, bid range, etc.), which distinguishes it from 'list_markets'. However, it does not explicitly name the sibling tool or contrast when to use each, so it falls short of a full 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?

The description provides no guidance on when to use this tool vs. alternatives like 'list_markets' or 'search_jobs'. It only states what it does; the 'when' is left entirely to inference. There are no exclusions or alternative suggestions.

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 carry the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar for additional disclosure is lower. The description repeats 'Read-only' and adds modest context by noting the tool reports live adapters and deployment stage, implying the output reflects dynamic environment state. This adds some value but not rich behavioral detail.

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 compact — roughly one sentence of substantive content plus a short 'Read-only' safety cue. The colon structure front-loads the purpose and lists the covered topics efficiently. The only minor redundancy is restating 'Read-only', which duplicates the annotation, but it adds little length and serves as an immediate safety signal.

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

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

For a parameterless, read-only informational tool with no output schema, the description adequately covers what the agent gets back (settlement currency, live adapters, deployment stage) and that the call is non-mutating. No prerequisites, arguments, or exclusions are needed. It is complete for the tool's simplicity.

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 has zero parameters and 100% schema description coverage, so there is nothing for the description to compensate for. The description makes no parameter claims that could mislead an agent. This matches the baseline for a parameterless tool.

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 the tool's function with a clear resource ('how Torquantis works') and enumerates the specific content it provides: settlement currency, live protocol adapters, and deployment stage. This scope distinguishes it from the sibling tools, which target jobs, markets, access requirements, and capability taxonomies. It stops short of 5 because 'Describe how Torquantis works' reads partly as an instruction to the agent rather than a crisp statement of the tool's return value.

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 usage context is implied rather than stated: it should be used when an agent needs a high-level overview of the Torquantis protocol, its settlement mechanism, adapter status, and deployment stage. There is no explicit when-to-use/when-not-to-use guidance or naming of alternatives, so an agent must infer the distinction from the sibling names and domain content.

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, covering the safety profile. The description adds the specific return fields, which is useful, but it does not disclose additional behaviors like pagination, rate limits, or required access levels. It repeats 'Read-only' which is already captured by 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?

The description is a single, well-structured sentence that front-loads the primary action and resource, then lists the key data fields. There is no redundant information or fluff.

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-parameter, read-only list tool, the description conveys the essential return contents and the safety profile via annotations. It does not mention return format or pagination, but these are not critical for a simple listing operation, especially with no output schema required. Overall, the description provides enough context for an agent to call the tool 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?

The tool has zero parameters, so the input schema is trivially complete. Per the calibration guidelines, a tool with 0 params receives a baseline of 4. The description does not need to elaborate on parameters that do not exist.

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 clear verb 'List' and specifies the resource 'every capability traded on Torquantis' along with the data fields returned (reference price, supply and demand, historical success rate). The word 'every' distinguishes it from the sibling get_market, which focuses on a single market.

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 implies a broad listing use case but does not explicitly state when to use this tool versus get_market or other siblings. There is no mention of alternatives or exclusion criteria, so the usage context 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, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those flags: budgets are denominated in TQC, and 'each response states the current real-money settlement state rather than assuming it.' It also reassures that the call 'commits you to nothing.' This is useful non-obvious behavior not captured in the schema or 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 sentences, each earning its place: what the tool lists, how to invoke it, and the critical caveat about budget units and settlement state. The most important scoping information is front-loaded in the first sentence, and there is zero filler or redundancy.

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

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

For a simple read-only list tool with two optional, fully documented parameters and strong safety annotations, the description supplies everything an agent needs: the object being listed, the response contents, default invocation, unit semantics, and read-only reassurance. No output schema exists, but the description explicitly states what each response contains.

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 schema covers both parameters (limit and cursor) at 100%, so the baseline is 3. The description adds little parameter-specific meaning beyond confirming that no arguments are required. It does not deepen the agent's understanding of pagination, but it does not need to given the schema 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?

The description names a specific verb ('List') and resource ('every machine-work opportunity currently open on Torquantis') and enumerates the response contents: capability, budget, deadline, and verification method. It is clearly distinguishable from the sibling get_job (single job) and search_jobs (search-focused) by emphasizing the full set of currently open opportunities.

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

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

The description gives clear usage context: 'Call this with no arguments to see everything open.' This tells the agent when to use this tool and how to invoke it. It does not explicitly name sibling alternatives or exclusions, so it stops short of full when/when-not routing, but the intended use case is unambiguous.

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 the description adds useful context: every result includes the governing contract and settlement state, and calling with no arguments returns everything open. The final 'Read-only' merely repeats the annotation, so it adds no extra behavioral credit.

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 concise and front-loaded, with the opening sentence capturing action and scope. The redundant 'Read-only' clause is a minor waste, but overall the structure is clean and every other sentence earns its place.

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

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

For a read-only search tool with 7 optional parameters and no output schema, the description provides necessary context: filter dimensions, no-args behavior, and key return fields. It does not mention default status behavior or result ordering, but the schema covers defaults; the main gap is lack of explicit relationship to list_open_jobs.

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 86%, so the schema already documents the parameters. The description names filter categories (capability, budget range, verification type, deadline) but adds no syntax or deeper semantics 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 ('Search current machine-work opportunities on Torquantis') and enumerates filter dimensions. However, it does not explicitly distinguish itself from the sibling list_open_jobs, so an agent must infer the difference from the word 'search' and the filter 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 gives a clear trigger ('what work can I do here?') and explicit no-argument versus narrowing instructions. It does not state exclusions or compare against list_open_jobs/get_job, so when-not-to-use guidance is missing.

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