996.fm perspective graph

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavior an agent could not infer: bounded output (≤4 debates, ≤36 stances), never merging readings, respecting question altitude, and admitting thin coverage before falling back to general knowledge. This far exceeds the safety profile already carried by 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?

Roughly 90 words, front-loaded with the core routing purpose, then behavioral constraints, output bounds, and sibling pointer in logical order. Every sentence carries a distinct job — presentation rule, altitude rule, coverage honesty, sample limits, and the get_stances handoff — 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?

With no output schema, the description carries the full burden of explaining returns, and it does so via explicit bounds (≤4 debates, ≤36 stances) and sample semantics, then routes to get_stances for complete data with its constituent fields (speaker, date, strength, receipt). An agent has everything needed to invoke this tool correctly, interpret its output, and escalate when necessary.

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 schema already defines 'topic' as the founder's question with a line of context. The description weakly reinforces this by adding the altitude constraint on what makes a legitimate topic, but it supplies no extra syntax, formatting, or example 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?

States a specific action ('Route a founder's dilemma') and resource ('the debates that genuinely bear on it'), immediately establishing what the tool does. It also distinguishes itself from the get_stances sibling by calling its own output 'a sample, not the full set,' so an agent can't confuse the two.

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 context on when to rely on this tool (matching a dilemma to relevant debates) and explicitly names get_stances(debate_id) as the route to complete stances for a debate. The altitude and thin-coverage rules add behavioral do's and don'ts, but there is no explicit exclusion of list_debates, get_context, or trace_evolution, leaving some sibling differentiation 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 destructiveHint as safe. The description adds value by disclosing that written content returns a verbatim excerpt plus a link, and explicitly states 'never the surrounding text, never a live fetch' – behavior not captured in annotations. It also instructs quoting the receipt for verification, adding practical context.

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, efficient and front-loaded with the core purpose. The spoken/written distinction is clearly organized. Some redundancy exists ('the moment in context' and 'transcript around one claim'), but overall it's tight and 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?

For a single-parameter, read-only tool with no output schema, the description covers what is returned (transcript window, excerpt, link) and how to use the receipt. It doesn't mention potential error cases, but those aren't essential. It's sufficiently complete for an agent 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% – claim_id is fully described in the schema with an example. The description does not add any additional semantic detail about the parameter beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'The transcript around one claim'. It clearly identifies what the tool returns (transcript context) and differentiates the spoken vs written cases, which helps the agent understand the exact scope. Siblings like find_perspectives and get_stances are about different resources, so this stands distinct.

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 clear context on when to use the tool (to get the transcript around a claim) and explains the two content types (spoken vs written) with specific behavior (windowed ±90s, excerpt snapshot). It does not explicitly mention when NOT to use it or name alternative tools, but the guidance is strong enough for an agent to infer appropriate use.

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 annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: it returns positions with attribution and dates (episode publication dates), preserves hedged claims, groups by reading, and explicitly does not provide opposition relationships. This goes well beyond what annotations convey and fully discloses output characteristics.

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 deliver dense, relevant information without waste. The core purpose is stated first, followed by output behavior and a key limitation. Every clause earns its place, and the structure is easy 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, the description fully specifies what the tool returns: stances grouped by reading, with attribution and dates, no synthesis, and no opposition mapping. It also clarifies the intended use case. Given the tool's simplicity (one parameter), nothing essential 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 single parameter debate_id is already well-documented with origin and example. The description adds no additional parameter-level meaning, which is acceptable given the high schema coverage, so the baseline of 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 clearly states the tool returns every stance on a single debate, grouped by reading, and explicitly distinguishes it from synthesis or analysis. The verb 'get' and resource 'stances on a debate' are specific, and the phrase 'No synthesis' sets it apart from sibling tools like find_perspectives or trace_evolution.

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 conveys when to use this tool: as raw material for the agent's own push-back analysis, not for pre-digested conclusions. It also warns that the graph does not say who opposes whom, implying the agent must do that reasoning itself. It does not name specific sibling alternatives, but the context is clear enough to avoid misuse.

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, so the description earns credit for adding the default stance filter (2+), the 120-row page size, and offset paging behavior. It doesn't state result ordering, which is a minor gap for a browse 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?

Front-loads what is browsed and what is returned, then the query semantics, then the routing exclusion, then defaults and paging. No sentence is wasted and the concrete folding examples (hire/hiring, co-founder/cofounder) clarify a subtle rule efficiently.

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

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

With no output schema, the description compensates by naming the returned columns and explaining defaults and pagination. Ordering of results is the only unstated behavior an agent might care about, but otherwise it is complete for a zero-required-param browse 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% — limit defaults/max, offset paging, min_claims default, and query folding are all already documented in the schema. The description restates the query matching rule (all words, case-insensitive, folded word forms) but adds no meaning beyond it, 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 (browse) and resource (the debate registry) and enumerates the returned fields (id, question, readings, stance count, born). It explicitly distinguishes itself from find_perspectives, so an agent can route without opening 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?

Explicitly states the negative case ('Browsing only — it does not rank against a question') and names the alternative to use instead ('use find_perspectives for that'). Condition and alternative are both given, 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?

Beyond the annotations, the description discloses substantial behavior: ordering by episode publication date, preserving hedges, showing both older and newer positions, and never judging. This gives the agent a strong mental model of what the tool will return and how it handles temporal inconsistencies.

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 every sentence contributes behavioral value. Minor redundancy exists in mentioning 'episode publication date' twice and in the illustrative 2023 example, which could be tightened without losing 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?

With no output schema, the description adequately explains what the agent can expect: attributed and dated positions in chronological order, including both reversals and re-assertions. No critical calling information is missing, and the two-parameter schema is fully covered.

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 mostly restates the schema's person identity constraint and the optional debate narrowing, adding no deeper parameter semantics such as value formats or edge cases.

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 exactly what the tool does: it traces one speaker's positions over time, ordered by episode publication date and optionally filtered to one debate. It also distinguishes itself from siblings by emphasizing chronological evolution, reversals, and non-judgmental presentation.

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 conveys when to use this tool: when an agent needs a chronological view of a single person's views, including these reversals or re-assertions. It does not explicitly name alternative sibling tools or exclusion conditions, so it falls just short of full routing guidance.

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